Skip to main content

OpenAI 429 Errors: Rate Limits, Quota and Spend Limits

Updated for the OpenAI API error codes and rate limit guides, including the current GPT-6 family. Tested on the OpenAI Python SDK 1.x and later.

A 429 from the OpenAI API does not mean one thing. The same status covers a temporary requests-per-minute limit, a ramp-rate penalty for traffic that grew too fast, an exhausted credit balance, and a hard spend cap on a project. Treating all of them as "slow down and retry" is the mistake behind most of the endless retry loops people report, because retrying a billing error never restores access. The response body tells you which case you are in, and the recovery for each is different.

This tutorial separates the cases that share the 429 status, shows how to branch on error.code instead of the status alone, and covers the retry behavior that actually helps.

What the error looks like

The envelope is consistent, but the fields inside it are not interchangeable. Three typical bodies:

{
  "error": {
    "type": "rate_limit_error",
    "code": "slow_down",
    "message": "Your request rate increased too quickly."
  }
}
{
  "error": {
    "type": "insufficient_quota",
    "code": "credit_balance_exhausted",
    "message": "You have no credits remaining."
  }
}

The billing cases include credit_balance_exhausted, organization_spend_limit_exceeded, project_spend_limit_exceeded and organization_usage_limit_exceeded. An ordinary throughput limit arrives as rate_limit_error without one of those codes. The distinction matters more than the status because the Python SDK raises RateLimitError for every 429, so an except RateLimitError block catches billing failures too.

Why they share a status

HTTP does not have a status for "your account cannot pay for this request", and the API has historically leaned on 429 for account-level blocks as well as throughput. The error-code documentation says so plainly: for billing-related errors, inspect error.code, because the broader error.type can still be insufficient_quota across several distinct causes. It also states that retrying billing, spend, or quota errors will not restore API access.

The slow_down case is the subtlest. It can appear even when you are inside your requests-per-minute and tokens-per-minute limits, because it reflects how quickly traffic increased, not whether you exhausted a ceiling. The documented guidance is to follow Retry-After when present, reduce the rate, then ramp gradually, and to keep growth under roughly 50 percent every 15 minutes once you are pushing a million input tokens per minute.

Model overload is a separate condition that used to look like this one. It now returns 503 with the type service_unavailable_error and the code server_is_overloaded. Any handler that only catches 429 for throttling will miss it.

Fix 1: branch on the error code, not the status

Classify before you retry. The error body is available on the exception object, so parse the body rather than pattern-matching the message text, which is not a stable contract:

from openai import APIStatusError

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}

def classify(err: APIStatusError) -> str:
    body = getattr(err, "body", None) or {}
    code = body.get("code")
    err_type = body.get("type")

    if code in BILLING_CODES or err_type == "insufficient_quota":
        return "billing"
    if code == "slow_down":
        return "ramp"
    if err.status_code == 503 or code == "server_is_overloaded":
        return "overload"
    return "rate_limit"

A billing result should page a human, not sleep. A ramp result should halve the concurrency and increase it slowly afterward. A rate_limit result should wait and retry. Collapsing those three into one handler is why some services burn an hour of retries before anyone notices that the account simply ran out of credits.

Fix 2: retry with the server's delay, once

When the case is temporary, honor Retry-After and add jitter. The header gives a minimum wait in seconds, and the documentation explicitly asks you to add a small random delay so parallel clients do not synchronize their retries:

import random
import time

from openai import InternalServerError, RateLimitError

def call_with_retry(fn, attempts=4):
    for attempt in range(attempts):
        try:
            return fn()
        except (RateLimitError, InternalServerError) as err:
            if classify(err) == "billing":
                raise

            headers = getattr(getattr(err, "response", None), "headers", {}) or {}
            retry_after = headers.get("retry-after")
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay + random.uniform(0, 0.5))

    raise RuntimeError("retries exhausted")

Two rules keep this honest. Cap the total time spent retrying, not only the attempt count, because a single Retry-After of 120 seconds can blow past a request deadline in one iteration. And account for the SDK's own retries: the official SDKs already retry eligible 429 and 503 responses, so a wrapper like the one above can multiply traffic if the client is also configured to retry three times. Disable one layer.

Streaming adds a wrinkle. Throttling errors arrive as HTTP responses before the stream starts, but an error during streaming can arrive as an event after you have already consumed output. Do not automatically replay a request whose partial output you have already forwarded to a user.

Fix 3: make the ceiling intentional

Three configuration changes remove most quota surprises before they happen. Set a spend alert and, if the workload is bounded, a hard spend limit on the project rather than the organization, so one experimental service cannot exhaust the budget for everything else. Keep the output cap close to the real response size, because the token charge for a request is calculated from the larger of your output-token cap and the estimate derived from the request character count, which means an inflated cap costs throughput on every call. And move bulk work to the Batch API when latency does not matter: batches have separate limits and do not consume your synchronous rate budget.

For long documents, trimming the prompt beats any retry strategy. The token estimate is computed from the request itself, so a 60k token history that only needs the last 8k will throttle you at a fraction of the throughput you think you have.

Preventing it

Log error.type, error.code, the model, and the x-request-id header for every 429, and alert on billing codes separately from throughput codes. Read the x-ratelimit-remaining-requests and x-ratelimit-remaining-tokens headers to schedule work below the ceiling instead of discovering it at the wall. If you run a queue, add a circuit breaker that stops pulling jobs after a billing error until an operator resets it; the alternative is a queue that retries forever against an account that cannot serve a single request.

We use cookies for ads and analytics.