Documentation

Error handling

Status codes, the error object shape, and safe retries.

The gateway and upstreams use standard HTTP status codes. Client errors are in the 4xx range; server/gateway errors in 5xx.

Status codes

  • 400 — malformed request.
  • 401 / 403 — missing/invalid credential, or not entitled to this API.
  • 404 — no matching route (often a wrong path prefix or version segment).
  • 429 — rate limited; see Rate limits.
  • 5xx — upstream or gateway error; safe to retry idempotent calls.

Retrying safely

Retry only idempotent operations. Use exponential back-off with jitter, and honour Retry-After when present. For non-idempotent writes, use an idempotency key if the API supports one.