# Errors

Interpret status codes, error envelopes, and temporary versus permanent failures.

OpenAI-compatible endpoints normally return:

```json
{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "metadata": {}
  }
}
```

## Status codes

| Status | Meaning | Client action |
|---:|---|---|
| `400` | Invalid JSON, unsupported parameter, endpoint mismatch, or unsupported model capability | Correct the request; do not retry unchanged |
| `401` | Missing, invalid, expired, inactive, or conflicting credentials | Fix or rotate credentials |
| `403` | Valid key without model or operation permission | Request access or choose an allowed model |
| `404` | Unknown model or resource | Refresh the model catalog and correct the ID |
| `413` | Request body, context, media, or text input too large | Reduce input or output budget |
| `429` | Key rate/concurrency limit, global/model capacity, queue timeout, vision pool, or media worker saturation | Honor `Retry-After`; retry with jitter |
| `502` | Upstream transport or protocol failure | Retry cautiously; preserve the request ID |
| `503` | No currently ready route or a required provider/service is unavailable | Honor `Retry-After`; retry or choose another ready model |
| `504` | Generation or upstream timeout | Retry with backoff if the operation is safe to repeat |

Anthropic Messages uses its own error envelope. It maps relevant upstream `502`, `503`, and `504` failures to `529 overloaded_error`; ordinary rate and concurrency limits remain `429`.

## Request IDs

Generated API responses normally return `X-Request-ID` and `Inference-Id`. Record the value with your own sanitized logs. Never log the Authorization header or request/response bodies merely to diagnose an error.