Errors
Errors use HTTP status codes and a stable JSON body. Branch on the code field, not on the message.
Error body
{ "error": { "type": "insufficient_credit", "code": "insufficient_credit", "message": "Your credit balance is too low for this request. Add credit in the console.", "request_id": "req_4c1e9b" }}Every error includes a request_id. Quote it when you contact support; it is the fastest way to find the request.
Codes
| Status | Code | Meaning | Retry |
|---|---|---|---|
| 400 | invalid_request | The body is malformed, or a field has the wrong type or value. The message names the field. | No. Fix the request. |
| 401 | invalid_api_key | The key is missing, malformed, revoked or unknown. | No. Check the key. |
| 402 | insufficient_credit | The credit balance does not cover the request. | After you add credit. |
| 404 | model_not_found | The model id is not in the models list. | No. Use a listed id. |
| 413 | context_too_long | The messages plus max_tokens exceed the context length of the model. | No. Shorten the input. |
| 429 | rate_limited | Too many requests for this key. The Retry-After header says how long to wait. | Yes, after Retry-After. |
| 500 | internal_error | Internal server error. The request was not billed. | Yes, with backoff. |
| 503 | service_unavailable | The model is temporarily unavailable. Retry with backoff. | Yes, with backoff. |
Retrying safely
Retry only the codes marked as retryable, with exponential backoff and jitter, and stop after a few attempts. Do not retry a 402 in a loop: it fails until credit is added.