Error semantics — our contract

Most API trust is burned not by outages but by errors that lie about what happened. This page is a contract, not documentation of best effort.

The contract

1. 5xx means us, 4xx means you — always. If our infrastructure fails, you get a 5xx with an honest body. You will never see a fabricated 401 User not found because an internal lookup service was down.
2. Rate limits fail loud. Exceeding a limit returns 429 with Retry-After. We do not silently queue, degrade, or reroute your request to a different model than the one you asked for.
3. No silent model substitution. If the provider serving your requested model is down and you didn’t opt into fallbacks, the request fails with 502 and names the provider. Fallback routing is opt-in per request (route: "fallback"), never a default.
4. Every error has a machine-readable cause.

{
  "error": {
    "code": "provider_unavailable",
    "http_status": 502,
    "message": "anthropic upstream timed out after 30s",
    "provider": "anthropic",
    "request_id": "req_...",
    "retryable": true
  }
}

Error codes

HTTP	code	Meaning	Retry?
400	invalid_request	Malformed body, unknown parameter, context too long	No — fix the request
401	invalid_key	Key missing, revoked, or malformed. Only ever an auth problem	No
402	insufficient_credit	Balance too low for the request	After top-up
404	model_not_found	Unknown model id — check /models	No
429	rate_limited	Per-key or per-model limit hit; Retry-After header set	Yes, after the header
500	internal_error	Our bug. request_id included — send it to support	Yes, with backoff
502	provider_unavailable	Upstream provider failed or timed out; provider named	Yes, or opt into fallback
503	overloaded	Temporary capacity issue on our edge	Yes, with backoff

Incident honesty

During incidents the status page is updated first, and post-mortems name the real cause. If we ever violate this contract — an infra failure surfaced as a 4xx — that’s a bug; report it and we’ll fix it and say so in the changelog.