API errors

OpenAI 429 error: causes, fixes and retry code

A 429 is not one error. Read error.code: it can be a rate limit, exhausted credits, an organization or project spend cap, an organization usage cap, or a slow_down ramp-rate warning. Billing and quota errors require an account change, not a retry. Temporary rate limits should follow Retry-After with jittered backoff.

P
Plugsky Editorial Team
Verified 19 November 2026

Short answer: check error.code before retrying. If it is rate_limit_exceeded or slow_down, wait at least Retry-After, add jitter and retry with a cap. If it is insufficient_quota, credit_balance_exhausted, organization_spend_limit_exceeded or project_spend_limit_exceeded, retrying will not help; fix the billing or limit first.

429 codes and what to do

CodeMeaningAction
rate_limit_exceededRequests or tokens exceeded the assigned limitFollow Retry-After; slow down; check RPM/TPM/RPD/TPD
slow_downTraffic increased faster than the service allowsFollow Retry-After; reduce the ramp; increase gradually
insufficient_quotaQuota or billing issue, often a broad type for 429 billing errorsCheck credits and billing; do not retry blindly
credit_balance_exhaustedPrepaid credit balance is emptyAdd credits
organization_spend_limit_exceededOrganization monthly spend cap reachedRaise/remove the cap or wait for reset
project_spend_limit_exceededProject monthly spend cap reachedRaise/remove the project cap
organization_usage_limit_exceededOpenAI-assigned monthly usage limit reachedRequest a higher usage limit or contact support

Sources: OpenAI error codes and rate limits, verified 19 Nov 2026. Codes and headers change.

429 vs 503

A 429 is a limit you hit. A 503 with service_unavailable_error and server_is_overloaded means the model is temporarily overloaded. Both can include Retry-After; handle both, but inspect the code. A 503 is not a signal to raise your rate limit.

Read the headers before you retry

HeaderUse
Retry-AfterMinimum seconds to wait for a temporary limit or overload
x-ratelimit-limit-requestsRequest ceiling for the window
x-ratelimit-remaining-requestsRequests left in the window
x-ratelimit-reset-requestsTime until the request limit resets
x-ratelimit-limit-tokensToken ceiling
x-ratelimit-remaining-tokensTokens left
x-ratelimit-reset-tokensTime until the token limit resets
x-ratelimit-*-project-*Project-scoped limits when they apply

Log the headers with the request ID. A 429 investigation without the limit, remaining and reset values is guesswork.

Why you hit 429 below the published limit

  1. Token reservation. The limit is calculated from the maximum of max_tokens and the estimated prompt tokens. A 1K prompt with max_tokens: 4,000 is charged closer to 5K at admission.
  2. Rolling windows. A per-minute limit can be enforced over a rolling window. A burst at the end of one minute and the start of the next can exceed it even if the clock-minute average is compliant.
  3. Burstiness. A worker pool that fires 50 requests at once creates a spike no smoothed limiter can absorb. Add jitter and a client-side token bucket.
  4. Project and organization scopes. Limits apply at both levels and can be shared across models. Another project or teammate can consume the headroom.
  5. Shared model limits. Some model families share a TPM pool. A model can be throttled because a sibling model used the capacity.
  6. Ramp rate. slow_down can occur even when you are inside RPM/TPM because traffic increased too quickly. OpenAI’s rule of thumb is to increase by no more than 50% every 15 minutes once you reach 1M input TPM.
  7. Retries. Failed requests count toward the limit. A retry storm sustains the throttling it is trying to escape.

Retry code that respects Retry-After

import random, time
import openai
from openai import OpenAI

client = OpenAI(max_retries=0)

PERMANENT = {
    "insufficient_quota",
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}

def call_with_backoff(**kwargs):
    for attempt in range(6):
        try:
            return client.responses.create(**kwargs)
        except openai.RateLimitError as e:
            code = getattr(e, "code", None)
            if code in PERMANENT:
                raise
            retry_after = 0
            if getattr(e, "response", None) is not None:
                raw = e.response.headers.get("retry-after")
                if raw:
                    try:
                        retry_after = float(raw)
                    except ValueError:
                        retry_after = 0
            delay = max(retry_after, (2 ** attempt) + random.random())
            if delay > 60:
                raise
            time.sleep(delay)
    raise RuntimeError("rate limit retries exhausted")

Keep the SDK’s built-in retries disabled or account for them in your own cap; nested retry loops multiply requests. If the server asks for a delay longer than your budget, defer the request instead of retrying sooner.

Fix the workload, not just the retry

  • Lower max_tokens. Reserve the p95 completion length plus headroom, not the model maximum. This directly raises effective RPM.
  • Reduce input tokens. Trim retrieved context, shorten history and remove unused tool schemas.
  • Batch what can wait. The Batch API has separate limits and a lower price for deferrable work.
  • Ramp gradually. Increase traffic in steps, not a step function. Watch slow_down.
  • Separate workloads. Use different projects or keys for interactive, batch and internal traffic so one job does not starve another.
  • Request a higher limit. If the workload is legitimate and sustained, raise the tier or approved usage limit.

The rate-limit calculator converts RPM/TPM/RPD/TPD into effective throughput and shows which limit binds. The caching/batch calculator shows what a cache or batch lane does to the bill.

When a flat plan avoids the per-token 429

A flat-rate API still has rate limits, but the caps are published in advance and the bill does not move with token count. Plugsky’s plans are $8–$120/month with RPM, concurrency and daily limits on the pricing page. If your 429s come from token ceilings rather than burstiness, compare the flat-plan caps with your p95 workload before buying a higher per-token tier.

FAQ

What does OpenAI 429 mean?

A 429 means the request was rejected for a limit, but not always the same limit. Inspect error.code: it can be a rate limit, exhausted credits, an organization or project spend cap, an organization usage cap, or a slow_down ramp-rate warning. Billing and quota errors require an account change, not a retry.

Should I retry a 429?

Only a temporary rate-limit or slow_down error. Follow Retry-After when present, add jitter, cap attempts and total delay. Do not retry insufficient_quota, credit_balance_exhausted, organization_spend_limit_exceeded or project_spend_limit_exceeded; fix the billing or limit first.

Why do I get 429 below my RPM limit?

RPM is not the only limit. TPM, RPD, TPD, project-token limits, shared model limits, max_tokens reservation and ramp-rate slow_down can bind first. Retries also count toward the limit and can amplify the problem.

How do I calculate a safe request rate?

Convert every limit to requests per minute at your p95 token size, take the lowest value, then apply a safety margin. The rate-limit calculator does this and shows which limit binds.

Stop guessing which limit binds

Use the rate-limit calculator to turn RPM, TPM and daily caps into a safe sustained rate and a drain-time estimate.

Open the calculator → See plans