Skip to Content
Rate Limits & Errors

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:

LimitDefault per keyIn practice
Requests per minute100,000No effective cap
Tokens per minute100,000,000No effective cap
Monthly token budgetNoneUnlimited

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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute for this key
X-RateLimit-RemainingRequests still available in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the window regains capacity
HTTP/1.1 200 OK X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Reset: 1787151600

They 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

StatustypecodeCause
400invalid_request_errornullValidation failed; param names the field
401invalid_request_errormissing_api_keyNo Authorization: Bearer header
401invalid_request_errorinvalid_api_keyMalformed key, or no such key
403invalid_request_errorkey_revokedThe key was revoked
403invalid_request_erroraccount_pendingThe account is awaiting approval
403invalid_request_erroraccount_disabledAn administrator disabled the account
403invalid_request_errorbudget_exceededThe key’s monthly token budget is spent
404invalid_request_errormodel_not_foundUnknown or disabled model; param is model
404invalid_request_errorunknown_urlNo such endpoint
413invalid_request_errornullRequest body over 20 MB
422invalid_request_errornullThe model rejected a parameter value
429rate_limit_errorrate_limit_exceededRequests/min or tokens/min window exhausted
500api_errorinternal_errorBug on our side
502api_errorupstream_errorThe 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

StatusRetry?
400, 404, 413, 422No — fix the request
401No — fix the key
403No — the key, or the account, cannot be used
429Yes — wait Retry-After seconds
500Yes — a couple of attempts with backoff
502Yes — 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.