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.