TroubleshootingReference
Error codes
Every status and code the gateway returns, and what to do about it.
By the end: You can map a failure to its cause and its fix.
Every failure carries a stable machine-readable code. Branch on the code, not the message text.
| Status | Code | Meaning | Fix |
|---|---|---|---|
| 401 | invalid_api_key | The key is unknown or malformed. | Check the value and that it starts with sk_live_. |
| 401 | revoked_api_key | The key was revoked. | Create a new key. |
| 401 | unauthorized | No key was sent. | Add the Authorization header. |
| 402 | insufficient_balance | Balance is zero. | Redeem a code or contact an administrator. |
| 403 | account_suspended | The account is disabled. | Contact support. |
| 400 | invalid_request | Body is not a JSON object, or a field is missing. | Check model and messages. |
| 400 | model_not_found | The model is not served here. | Use an ID from GET /v1/models. |
| 404 | not_found | The route or action does not exist. | Check the path. |
| 413 | payload_too_large | Body exceeds the limit. | Send less data (1 MiB default). |
| 429 | rate_limit_exceeded | Too many requests. | Wait retry-after seconds. |
| 429 | quota_exceeded | A daily or monthly quota is spent. | Wait for the period to reset. |
| 502 | provider_error | The model service returned an error. | Retry with backoff; if persistent, try another model. |
| 502 | provider_unavailable | The service could not be reached. | Retry shortly. |
| 504 | provider_timeout | The model service timed out. | Retry, or reduce the request size. |
| 500 | internal_error | Unexpected gateway failure. | Retry once, then report the request ID. |
Request IDs
Every response carries x-request-id. Quote it when reporting a problem; it identifies the exact upstream attempt.