Errors & status codes

Gateway Protocol v1 · Production Reference

Documentation

One key, two compatible wire protocols, 15 frontier models. Read the quickstart or explore the API reference.

The gateway returns a consistent JSON error body for every failure, so retry logic can key off the status code rather than the message text.

Error response shape

json

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Per-minute request budget exhausted. Retry after 12s.",
    "code": 429,
    "retry_after": 12
  }
}

Status codes

401

unauthorized

Missing or invalid Bearer token — check your API key.

402

insufficient_balance

No active plan or its spend window is exhausted — buy or renew a plan on Billing.

429

rate_limit_exceeded

Over the per-minute or per-day budget. Honor retry_after.

500

gateway_error

Internal gateway failure. Safe to retry once after a short backoff.

504

upstream_timeout

The upstream model did not respond within the 30s cap.