Errors and rate limits
Understand error responses, request limits and when to retry.
Read an API error
An unsuccessful request returns an HTTP status and an error object. Use error.code to identify the condition and error.param, when present, to find the affected input. Keep the returned X-Request-ID when contacting support.
{
"error": {
"message": "model is not available",
"type": "invalid_request_error",
"code": "model_not_found",
"param": "model"
}
}Common errors and recovery
| HTTP status / code | What to do |
|---|---|
| 400 / invalid_json, invalid_request | Check JSON syntax, required fields and the selected model’s limits. Correct the request before retrying. |
| 401 / invalid_api_key | Check the full key and Bearer header. Create a replacement if the key was lost or revoked. |
| 403 / key_expired, ip_not_allowed, model_not_allowed | Check your key’s access restrictions. Use a valid key with access to the requested model. |
| 403 / account_suspended, account_blocked | Contact support about account access. |
| 429 / insufficient_quota | Review your account’s billing status. Contact support if payment options are unavailable. |
| 404 / model_not_found | Copy an available model ID from the catalog. Also check the request URL. |
| 413 / request_too_large | Reduce the request body, conversation length or attached input size. |
| 429 / rate_limit_exceeded | Wait for Retry-After and reduce request concurrency. |
| 500, 502, 503 / server error | Check service status. Retry a limited number of times with backoff when appropriate. |
Retry without duplicating work
- Honor Retry-After when the response supplies it. Use its value to schedule the next attempt.
- Use exponential backoff with jitter for retryable failures and cap the number of attempts.
- Do not repeat authentication, permission or invalid-request errors without fixing their cause.
- Check your SDK’s automatic retry behavior before adding another retry loop.
- A network timeout does not prove that no work was completed. A repeated request is a new generation and may incur additional usage.
For support, share the request ID, approximate time, public model ID, HTTP status and error code. Do not send your API key or private prompt content.
Manage request limits
The default account limit is 120 requests per minute across API keys. Your account or key may have a different limit. Creating additional keys does not increase an account limit.
| Response header | Meaning |
|---|---|
| X-RateLimit-Limit-Requests | The number of requests allowed in the reported window. |
| X-RateLimit-Remaining-Requests | Requests remaining in the current limit window. |
| X-RateLimit-Reset-Requests | Time until the reported limit window resets, expressed in seconds with an s suffix. |
| Retry-After | Seconds to wait before retrying a rejected request. |
Queue requests in your application and keep concurrency bounded. If a request is rejected because it is too large, reduce its input; waiting will not fix the payload.