# Errors

Status codes, error types, and which failures are safe to retry.

## Error responses

Every error carries an HTTP status and a JSON body with a stable `error.type`. Branch on `type`, not on the message text — messages may change.

| Status | Type | Notes | Retry |
| --- | --- | --- | --- |
| 400 | invalid_request_error | Malformed JSON, missing required field, or an invalid parameter value. Fix the payload — retrying unchanged will fail again. | No |
| 401 | authentication_error | Missing or invalid API key. Check the `Authorization: Bearer` header. | No |
| 403 | permission_error | The key is valid but not entitled to this model, endpoint, or region. | No |
| 404 | not_found_error | Unknown model ID or endpoint path. Verify the model name and base URL. | No |
| 408 | timeout_error | The request exceeded the server-side time limit. Shorten the prompt or reduce `max_tokens`. | Backoff |
| 410 | deprecated_model_error | The requested model has reached its sunset date and is no longer served. The error body carries the migration-guide URL — switch to the replacement model. | No |
| 413 | request_too_large | Request body exceeds the size limit, or the prompt exceeds the model context window. | No |
| 422 | validation_error | Semantically invalid request — e.g. a malformed tool schema or an unsupported parameter combination. | No |
| 429 | rate_limit_error | Rate or quota limit exceeded. Wait the `Retry-After` interval, then retry with exponential backoff. | Backoff |
| 499 | request_cancelled | The client disconnected before the response completed. Not billed. | Yes |
| 500 | api_error | Unexpected internal error. Retry with exponential backoff and jitter. | Backoff |
| 502 / 504 | upstream_error | A gateway or upstream inference node failed or timed out. Transient — retry with backoff. | Backoff |
| 503 | service_unavailable | The endpoint is temporarily unable to serve traffic, typically during a deploy or capacity event. | Backoff |
| 529 | overloaded_error | The service is at capacity. Back off aggressively and retry with jitter to avoid a thundering herd. | Backoff |

## Example bodies

Invalid request — fix the payload before retrying:

```
# HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "param": "messages",
    "message": "Field 'messages' is required."
  }
}
```

Token rate 429 — wait `Retry-After` seconds before retrying:

```
# HTTP/1.1 429 Too Many Requests
# Retry-After: 37
{
  "error": {
    "type": "rate_limit_error",
    "code": "token_rate_limit",
    "message": "Per-minute token budget exhausted."
  }
}
```

_Last updated: September 2, 2026_