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) andslow_down(your request rate rose too fast). Follow theRetry-Afterheader 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_errorandslow_down, honouringRetry-After. - Treat the four billing codes and
insufficient_quotaas 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 (atlaspay.life), a service that issues virtual USD cards for paying international services from Russia. Our write-up on which cards work for paying the OpenAI API and other AI providers is in Russian.
Top comments (0)