Answers

Why is the API returning 429, and what should I do?

A 429 means you have spent a rolling cap, not that you are banned. Our 429 comes with a Retry-After header saying how many seconds until the cap frees up — respect it, and the request succeeds. If you are seeing 402 instead, that is a different thing: no allowance and no balance.

Three failures people mix up

Where our 429 comes from

Plans hold an allowance for the billing period, plus two rolling caps on how fast it can be spent: a 5-hour window and a weekly one. They exist so one runaway agent loop cannot burn a month of allowance in an afternoon. Both are a percentage of the plan’s allowance, so a larger plan gets a proportionally larger burst — and both are visible as percentages in the console, with the reset time next to them.

If you keep a prepaid balance as well as a plan, you do not get throttled at all — spending past the window bills per token from the balance instead of returning 429.

The retry pattern

import time, openai

def call_with_retry(client, **kw):
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kw)
        except openai.RateLimitError as e:
            # Prefer the server's number over your own guess.
            wait = int(getattr(e, "response", None) and
                       e.response.headers.get("retry-after") or 2 ** attempt)
            time.sleep(wait)
    raise RuntimeError("still rate limited after 5 attempts")

If you are hitting it constantly

• Look at what is spending the allowance. In the console, the burn rate per model tells you this directly — the same tokens on a ×2.9 model cost nearly three times the window.
• Cut the context you resend. Most agent loops resend the entire history every turn; trimming it is usually the single biggest saving available.
• Move bulk work to the cheapest model and reserve the expensive one for the steps that need it.
• If the workload is genuinely that size, a larger plan raises both caps — they scale with the allowance.

FAQ