Rate Limits & Errors
Rate limits
Limits are enforced per API key over a 60-second sliding window — not per calendar minute, so a burst does not reset at the top of the minute.
A newly created key starts with no effective cap:
| Limit | Default per key | In practice |
|---|---|---|
| Requests per minute | 100,000 | No effective cap |
| Tokens per minute | 100,000,000 | No effective cap |
| Monthly token budget | None | Unlimited |
Two windows are checked independently:
- Requests per minute — counted when the request arrives.
- Tokens per minute — a request’s cost is unknown until it finishes, so the window is checked
before the call and credited afterwards with the total from
usage. A few large completions can therefore throttle the following minute.
Defaults are not a promise of unmetered access. An administrator may assign specific limits — and
a monthly token budget — to any individual key at any time, without reissuing it. The limits that
apply to your key are the ones in the X-RateLimit-* headers on every response, so read them
there rather than assuming the defaults.
Limits live on the key, not the account, so two keys of the same account can carry different ones. Ask an administrator to raise, lower or clear yours — no new key is needed.
When you are limited
Only a key with an assigned limit realistically gets here. 429 with a Retry-After header, in
seconds, derived from when the oldest request in the window expires — the message quotes the limit
that key actually carries:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json{
"error": {
"message": "Rate limit exceeded: 60 requests per minute.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"param": null
}
}The message states which limit you hit — requests or tokens.
Rate limit headers
Every /v1 response carries the state of your requests-per-minute window:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute for this key |
X-RateLimit-Remaining | Requests still available in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the window regains capacity |
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1787151600They appear on successful responses, on 429, and on error responses such as 400, so a client
always knows where it stands. Because the window slides, X-RateLimit-Reset is the moment the
oldest request in the window ages out — not the top of the next minute.
The headers describe the requests window. The tokens-per-minute window is reported only when
you hit it, through the 429 message; track token spend from the usage field of each response.
Error format
Every error — including the gateway’s own auth and rate-limit rejections — uses the OpenAI envelope, so SDK error handling works unchanged:
{
"error": {
"message": "Human-readable description.",
"type": "invalid_request_error",
"code": "invalid_api_key",
"param": null
}
}code is null for request-validation failures; param names the offending field when the gateway
can identify it.
Every error code
| Status | type | code | Cause |
|---|---|---|---|
| 400 | invalid_request_error | null | Validation failed; param names the field |
| 401 | invalid_request_error | missing_api_key | No Authorization: Bearer header |
| 401 | invalid_request_error | invalid_api_key | Malformed key, or no such key |
| 403 | invalid_request_error | key_revoked | The key was revoked |
| 403 | invalid_request_error | account_pending | The account is awaiting approval |
| 403 | invalid_request_error | account_disabled | An administrator disabled the account |
| 403 | invalid_request_error | budget_exceeded | The key’s monthly token budget is spent |
| 404 | invalid_request_error | model_not_found | Unknown or disabled model; param is model |
| 404 | invalid_request_error | unknown_url | No such endpoint |
| 413 | invalid_request_error | null | Request body over 20 MB |
| 422 | invalid_request_error | null | The model rejected a parameter value |
| 429 | rate_limit_error | rate_limit_exceeded | Requests/min or tokens/min window exhausted |
| 500 | api_error | internal_error | Bug on our side |
| 502 | api_error | upstream_error | The model provider failed or was unreachable |
Examples
Validation — note param:
{
"error": {
"message": "Too big: expected number to be <=2 (at `temperature`)",
"type": "invalid_request_error",
"code": null,
"param": "temperature"
}
}Unknown model:
{
"error": {
"message": "The model `gpt-4o` does not exist or you do not have access to it.",
"type": "invalid_request_error",
"code": "model_not_found",
"param": "model"
}
}Parameter errors from the model
Some validation happens at the gateway and some at the model itself. When the model rejects a
parameter, its own message comes back in the same envelope with a 400 or 422 — not a 502:
{
"error": {
"message": "reasoning_effort must be one of [none low high max] for this model",
"type": "invalid_request_error",
"code": null,
"param": null
}
}These are permanent: the identical request will fail again. Retrying a 4xx cannot help, and an
agent that retries one loops until it gives up. Real examples seen in production are an
unsupported reasoning_effort value and tools: [] — send at least one tool or omit the field.
Upstream failure — the provider’s own message is passed through when it sends one:
{
"error": {
"message": "model not found",
"type": "api_error",
"code": "upstream_error",
"param": null
}
}Monthly token budgets
A key can carry a monthly token budget. Once the tokens charged to it in the current calendar month (input + output, reasoning included) reach that budget, requests are refused:
{
"error": {
"message": "Monthly token budget exhausted: 1,000,000 tokens. The budget resets at 2026-09-01T00:00:00.000Z.",
"type": "invalid_request_error",
"code": "budget_exceeded",
"param": null
}
}The window is the UTC calendar month, so the budget resets at 00:00 UTC on the 1st — there is no rolling 30-day window to reason about. Budgets are per key, so splitting work across keys gives each its own allowance. Ask an administrator to raise the budget or clear it (a cleared budget is unlimited).
Accounts can also be disabled outright, which returns 403 account_disabled for every key the
account owns.
Retry guidance
| Status | Retry? |
|---|---|
| 400, 404, 413, 422 | No — fix the request |
| 401 | No — fix the key |
| 403 | No — the key, or the account, cannot be used |
| 429 | Yes — wait Retry-After seconds |
| 500 | Yes — a couple of attempts with backoff |
| 502 | Yes — the provider may be briefly unavailable |
The OpenAI SDKs already do this. Rolling your own:
import time
import openai
def with_retries(call, attempts=4):
for attempt in range(attempts):
try:
return call()
except openai.RateLimitError as error:
wait = float(error.response.headers.get("retry-after", 2 ** attempt))
time.sleep(wait)
except (openai.APIStatusError, openai.APIConnectionError) as error:
status = getattr(error, "status_code", 500)
if status < 500:
raise # 4xx will not fix itself
time.sleep(2 ** attempt)
raise RuntimeError("out of retries")Retry 429 and 5xx only, respect Retry-After, and add jitter if many workers share one key —
otherwise they all retry in lockstep and hit the limit together.
Streaming errors
Errors before the first chunk arrive as JSON with a status code. Once the stream has started the
status is already 200, so a later failure just ends the stream: a stream that stops without a
finish_reason is incomplete. See Streaming.