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:

{
  "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:

{
  "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:

{
  "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

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.

Start Here

Build Your First App

Network

Identity & Roles

Capsules

Evidence

Verification

Provenance

PRESS Economy

Bounties

Data Model

API

RPC

PressKey

SDK & Integration

Operations & Security

Reference

Errors & Pagination

State unavailable

Route not found

Method not allowed

Client error helper

Retry policy

​Errors and pagination

​Pagination

​State unavailable

​Route not found

​Method not allowed

​Client error helper

​Retry policy

Errors and pagination

Pagination

State unavailable

Route not found

Method not allowed

Client error helper

Retry policy