> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Status Codes

> Error responses, common messages, and how to handle them.

# 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, or Auto Agent plan required                         |
| 429  | Too Many Requests | Plan window/weekly/burst limit exceeded, or temporary abuse/capacity throttle on this key |
| 502  | Bad Gateway       | The upstream provider returned an error after retries                                     |
| 529  | Overloaded        | No healthy upstream providers for the requested model right now                           |

## Example error body

```json theme={null}
{
  "error": "The model provider is temporarily unavailable. Please try again in a moment."
}
```

A temporary abuse/capacity throttle 429 also returns the reduced rate and a retry hint in the body:

```json theme={null}
{
  "error": "Temporary rate limit applied due to high load. Please retry shortly at a lower rate (up to 10 requests per minute).",
  "retry_after_seconds": 58,
  "max_rpm": 10
}
```

## 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.
* **429 has two causes:**
  1. **Plan rate limit** — your key exceeded its per-window allowance, weekly cap, or per-minute burst limit. 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.

## See also

* [Rate Limits](/api-reference/rate-limits)
* [Troubleshooting](/troubleshooting/common-errors)