Production

Errors & failover

Standard HTTP codes, an OpenAI-shape error body, and automatic provider failover on paid plans so transient upstream failures don't reach your user.

HTTP status codes

Code	Meaning	What to do
`400`	Invalid request — bad JSON, unknown model, bad params.	Read `error.message`. Fix the request.
`401`	Missing / malformed / revoked key.	Mint a new one.
`402`	Spend cap reached on this key for the month.	Raise the cap or wait for the next billing cycle.
`429`	Plan RPM limit. Body's `error.type = "rate_limit_exceeded"`.	Back off ≥ 60s. Upgrade plan if persistent.
`5xx`	Upstream provider error.	Auto-failover engages if your route has multiple targets (paid plans).

Error body shape

{
  "error": {
    "message": "Rate limit exceeded for plan 'free'. Upgrade or slow down.",
    "type": "rate_limit_exceeded"
  }
}

Automatic failover

If a route has multiple targets (configured on the dashboard's Routes page) and the primary provider returns 5xx, we transparently retry on the next target before returning to you. Each attempt is logged with the provider name + status code on its own row in your activity log — easy to spot which upstream is misbehaving.

When to retry from your side

Use exponential backoff (e.g. 1s, 2s, 4s, max 3 attempts) for:

429 — wait at least until the time in X-RateLimit-Reset-Plan.
5xx — only if your route is single-target (no auto-failover available).
Network errors (connection reset, timeout).

Don't retry 400 / 401 / 402 — they're deterministic and will fail again.