Errors and rate limiting
Applies to: all
/v1endpoints
1. Error format#
All non-streaming error response bodies use the following shape:
{
"error": {
"message": "The model 'gpt-4o' does not exist.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}messageis human-readable and not guaranteed to be stable; do not use it for program logic.codeis machine-readable and intended for branching.typeis a coarse category (authentication_error/rate_limit_error/billing_error/invalid_request_error/server_error).
2. Error code table#
| code | HTTP | Meaning | Suggested handling |
|---|---|---|---|
missing_api_key |
401 | No credentials supplied | Add Authorization: Bearer |
invalid_api_key |
401 | Key does not exist or has been revoked | Use a different key |
invalid_token |
401 | JWT expired or invalid | Log in again |
unauthorized |
401 | Other authentication failure | Check your credentials |
forbidden |
403 | Not permitted (e.g. calling /v1/images/edits with an nx- key) |
Use a JWT instead |
invalid_request |
400 | Invalid parameters | Correct them according to message |
model_not_found |
404 | Model does not exist or is not exposed | Confirm with GET /v1/models |
not_found |
404 | Resource does not exist or does not belong to the current user | Check the ID |
conflict |
409 | Uniqueness conflict | Query, then retry |
payload_too_large |
413 | Request body/file exceeds the limit | Shrink the file (files ≤10MB, global body ≤32MB) |
rate_limit_exceeded |
429 | RPM exceeded | Back off according to Retry-After |
token_rate_limit_exceeded |
429 | TPM exceeded | Back off according to Retry-After |
quota_exceeded |
429 | Monthly plan quota exhausted | Upgrade your plan or wait until next month |
insufficient_balance |
402 | Insufficient balance | Top up, then retry |
inference_unavailable |
502 | Upstream unavailable (failover already attempted) | Safe to retry |
model_overloaded |
503 | Upstream overloaded | Safe to retry |
internal_error |
500 | Server-side exception | Retry; if it persists, report the issue |
The upstream's real model name, provider URL, and raw error text never appear in responses (opacity is a hard rule); job-related errors return only fixed text.
3. Rate limiting#
Bucketed by (API key, model) in one-minute windows. Resolution order:
- Key-level override (set in the console)
- Model-level default
- Plan default
- System fallback: 60 RPM / 40,000 TPM
429 response headers#
| Header | Description |
|---|---|
X-RateLimit-Limit-Requests |
RPM limit |
X-RateLimit-Remaining-Requests |
Requests remaining this minute (0 when exceeded) |
X-RateLimit-Reset |
Window reset time (Unix seconds) |
X-RateLimit-Limit-Tokens |
TPM limit |
X-RateLimit-Remaining-Tokens |
Tokens remaining this minute (0 when exceeded) |
Retry-After |
Suggested wait in seconds |
Client guidance#
import time, random
from openai import OpenAI, RateLimitError
def call_with_retry(fn, attempts=4):
for i in range(attempts):
try:
return fn()
except RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", 1))
time.sleep(wait + random.uniform(0, 0.5))
raise- Only retry 429 / 502 / 503 / 500; retrying 4xx parameter errors is pointless.
- Exponential backoff with jitter; respect
Retry-After. - Image jobs are asynchronous: a 202 on submission does not mean generation has completed; when retrying a submission, reuse the
idempotency_key.
4. Idempotency#
| Endpoint | Idempotency key | Semantics |
|---|---|---|
/v1/images/generations |
idempotency_key (optional) |
The same key from the same user returns the original job |
/v1/images/edits |
idempotency_key (optional) |
Same as above |
Text chat requests have no idempotency guarantee; a network retry creates a new billable request.
5. Billing-related states#
| Scenario | Behavior |
|---|---|
| Insufficient balance | 402 before reaching the upstream; no charge is incurred |
| Failure midway through a request | The full reservation is returned |
| Job failure/cancellation | The full reservation is returned |
| Disconnect after streaming has started | Billed for delivered content; zero delivery is not charged |