---
title: Errors
description: Read and handle API errors consistently.
---

Errors use an OpenAI-compatible envelope. Check the HTTP status first, then use `error.code` for programmatic handling. Keep `request_id` when it is present so support can trace a request.

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "auth_failed",
    "param": null,
    "request_id": "…"
  }
}
```

## Common responses

| Status | Meaning | Client action |
| --- | --- | --- |
| `400` | Invalid input or unsupported option | Correct the request; do not retry unchanged. |
| `401` | Missing, invalid, or expired credential | Replace the credential. |
| `402` | Insufficient balance | Add balance before retrying. |
| `403` | The key lacks the needed scope | Use a key with the required permission. |
| `404` | Resource is unavailable to this account | Check the identifier and access. |
| `413` | Request or upload is too large | Reduce the request or split the file. |
| `429` | Rate or authentication throttle | Respect `Retry-After`, then retry with backoff. |
| `5xx` | Temporary API or capacity failure | Retry idempotent work with bounded backoff. |

Do not present raw API messages directly to end users. Map stable error codes to clear product copy and log the request ID separately.