> ## Documentation Index
> Fetch the complete documentation index at: https://docs.presschain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Pagination

> Handle bounded pagination and explicit service errors in the current PressChain Rust API.

# Errors and pagination

The current API surface is small, but clients should still treat HTTP status and structured error code as part of the contract.

## Pagination

Both bounty list routes accept:

* `limit`
* `offset`

`limit` defaults to `25` and is clamped to a maximum of `100`. `offset` defaults to `0`.

A request for `limit=10000` does not force an enormous state read. The server clamps the request to its supported page size.

## State unavailable

When the configured bounty state cannot be read, health and bounty list handlers return `503 Service Unavailable` with:

```json theme={null}
{
  "error": {
    "code": "bounty_state_unavailable"
  }
}
```

Do not translate this into an empty collection. “No proposals exist” and “proposal state cannot be read” are different facts.

## Route not found

Unknown read routes return `404`:

```json theme={null}
{
  "error": {
    "code": "route_not_found"
  }
}
```

A 404 for a documented route usually indicates a base URL or deployed API version mismatch.

## Method not allowed

Unsupported write methods return `405`:

```json theme={null}
{
  "error": {
    "code": "method_not_allowed",
    "message": "This API is read-only."
  }
}
```

Do not retry a 405. The client is asking the service to perform an operation it intentionally does not support.

## Client error helper

```ts theme={null}
export async function toApiError(response: Response) {
  let payload: any = null;
  try {
    payload = await response.json();
  } catch {}

  const code = payload?.error?.code ?? `http_${response.status}`;
  const message = payload?.error?.message ?? response.statusText;

  return Object.assign(new Error(message), {
    status: response.status,
    code,
  });
}
```

Keep status and code as fields so retry and reporting logic does not need to parse human-readable strings.

## Retry policy

Read-side `503` responses can be retried with bounded exponential backoff. A `404` or `405` generally needs client or deployment correction, not repeated traffic.

Keep retries observable and capped. Infinite background polling can turn a state-layer outage into an unnecessary load problem.