Errors & Status Codes

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

Common status codes

Code	Meaning	Typical cause
400	Bad Request	Invalid JSON, missing required fields, unknown model for the route
401	Unauthorized	Missing/invalid `Authorization: Bearer` or revoked key
403	Forbidden	Model not permitted for this API key
429	Too Many Requests	RPM or RPD limit exceeded for the key
503	Service Unavailable	No healthy upstream providers for the requested model right now

{
  "error": "The model provider is temporarily unavailable. Please try again in a moment."
}

Upstream failures never count against quota. If we return 503 “No available providers” or forward an upstream 5xx as a capacity issue, it does not consume your plan or credit balance.
429 only happens for your rate limits, never because an upstream is busy (we fail over instead).

“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.