OpenAI 429s that retries won't fix: credit_balance_exhausted and spend limits

chel.it852 — Wed, 11 Nov 2026 09:23:04 +0000

Most retry helpers treat every HTTP 429 from the OpenAI API the same way: wait, back off, try again. That is right for rate limits. It is wrong for billing errors, which also come back as 429. In the words of the error codes guide, retrying billing, spend or quota errors won't restore API access.

This post shows how to tell them apart in code, and how the prepaid billing model behind them affects the way you top up.

The 429s you should retry

rate_limit_error (requests or tokens per minute) and slow_down (your request rate rose too fast). Follow the Retry-After header when it is present, then back off.

The 429s you should not retry

These are billing errors. The guide says to inspect error.code for the specific cause, while error.type can still be the broader insufficient_quota:

credit_balance_exhausted — the organization has no prepaid credits left.
organization_spend_limit_exceeded — the organization hit its own spend limit.
project_spend_limit_exceeded — a project hit its spend limit.
organization_usage_limit_exceeded — the organization reached its OpenAI-assigned usage limit.

Each one needs a human: add credits, raise a limit or ask for a higher tier. Until then every retry fails the same way.

Handling it in Python

With the official openai package (v1+), all of these raise RateLimitError, so look at the body before retrying:

import time
from openai import OpenAI, RateLimitError

client = OpenAI()

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

class BillingBlocked(Exception):
    pass

def complete(messages, retries=5):
    delay = 1
    for _ in range(retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o-mini", messages=messages
            )
        except RateLimitError as e:
            body = e.body if isinstance(e.body, dict) else {}
            if body.get("code") in BILLING_CODES or body.get("type") == "insufficient_quota":
                # Not transient: stop the job and alert a human.
                raise BillingBlocked(body.get("code") or "insufficient_quota") from e
            retry_after = e.response.headers.get("retry-after")
            time.sleep(float(retry_after) if retry_after else delay)
            delay = min(delay * 2, 30)
    raise RuntimeError("rate limited after retries")

A distinct exception lets a worker queue pause all jobs at once instead of every job retrying on its own, and lets you send one alert instead of thousands of identical log lines.

Why credits run out: prepaid billing

API usage is paid from prepaid credits (OpenAI help). Three details matter for code that runs unattended:

The minimum credit purchase is $5.
Credits expire one year after purchase, so a large stock bought "just in case" can go to waste.
Auto-recharge tops the balance up when it drops below a threshold. Each recharge is a separate card charge. If the card declines it, you may first learn about it from credit_balance_exhausted.

Card fees change the math on small top-ups

Many cards, especially prepaid and virtual ones, charge a fixed fee per purchase. On a $20 subscription, $0.80 is 4%. On a $5 credit top-up it is 16%. If auto-recharge buys $5 several times a month, the fees grow faster than you expect.

Two practical rules:

Set the auto-recharge amount so it fires once or twice a month, but not so high that credits sit unused toward the one-year expiry.
If the card declines a charge, do not retry it many times in a row. Many issuers limit declined attempts. Find the reason first: billing address, 3DS confirmation or not enough money on the card.

Checklist

Retry rate_limit_error and slow_down, honouring Retry-After.
Treat the four billing codes and insufficient_quota as a hard stop.
Alert once and pause the queue.
Keep a project spend limit so a bug cannot drain the balance.
Size auto-recharge to your monthly usage and check what your card charges per purchase.

Disclosure: I work on Atlas, a service that issues virtual USD cards for paying international services from Russia. Our write-up on which cards work for API providers is in Russian, here.