Skip to main content

​
Errors & Status Codes

Openference aims to return clear errors while protecting upstream details when appropriate.

​
Common status codes

​
Example error body

Limit responses are machine-readable. A burst-limit 429 carries a Retry-After header plus type, code, retry_after_seconds, and max_rpm in the body:
Quota exhaustion with no credit balance returns 402 with a resets_at timestamp (ISO-8601) telling you when the allowance returns:
On /v1/messages (Anthropic-native), limit errors use the Anthropic error envelope — { "type": "error", "error": { "type": "rate_limit_error", "message": "...", "code": "..." } } — so Anthropic-SDK clients surface the message natively. Successful responses also carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers (your burst budget and when the 60-second window rolls) — see Rate Limits.

​
Important semantics

  • Upstream failures never count against quota. A 529 “Overloaded” capacity response or a 502 upstream error does not consume your plan or credit balance.
  • Limit responses are retry-friendly:
    1. Plan rate limit — your account exceeded its per-window allowance, weekly cap, or per-minute burst limit. Burst-limit 429s carry a Retry-After header (exact time until your sliding 60-second window frees capacity) and a code/retry_after_seconds body. Without credit balance, window/weekly exhaustion returns 402 with a resets_at timestamp; on-demand credits may allow continued use past the per-window allowance and weekly cap.
    2. Temporary abuse/capacity throttle — a short-lived lower per-minute cap applied to this key only when automated signals detect disproportionate high-volume load that may harm shared model capacity. Credits do not bypass this throttle. This is a rate reduction, not a block — the key keeps serving at the lower rate, so retry shortly at the reduced rate rather than waiting out the throttle. The response includes a short Retry-After header (seconds until your next retry, typically under a minute — not the full throttle duration) and retry_after_seconds / max_rpm fields in the body.
  • 529 vs 429: Capacity issues return 529 Overloaded (with a Retry-After header) while we fail over or wait for providers to recover. They do not trigger the abuse throttle by themselves during platform-wide capacity events.

​
Capacity messages you may see

  • “We’re experiencing heavy usage right now, which may cause increased latency or temporary unavailability…”
  • “The model provider is temporarily unavailable…”
These indicate all configured routes for that model are currently unhealthy or rate-limited on the upstream side.

​
ZDR mode denial

API keys with ZDR mode enabled (see the FAQ) are hard-restricted to the providers we classify as zero-data-retention. Requesting a model that has no ZDR route — for example MiniMax M3 — returns 403 with code model_not_available_in_zdr_mode:
The same models are hidden from GET /v1/models for that key, so well-behaved clients never send them.

​
See also