Fix: "You exceeded your current quota, please check your plan and billing details" — OpenAI 429 insufficient_quota

TL;DR — insufficient_quota is a billing error wearing a 429 costume. It does not mean you sent requests too fast; it means your API account has no usable credit: no payment method / prepaid credits on the API account, a hard usage limit already hit, or an expired free grant. The fix is in the billing dashboard, not in your code — add credits or raise the limit, then wait a few minutes for it to propagate. Retrying with backoff will never fix this one.

The error

HTTP 429
{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details. ...",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

The status code is 429, which every retry library on earth interprets as "slow down and try again." That is exactly the wrong model here — and it is why agents wrapped in exponential backoff can burn half an hour retrying an error that cannot succeed.

Rate limit vs. quota: the distinction that matters

OpenAI uses 429 for two completely different conditions, distinguished by the error type:

| Error type | What it means | Does retrying help? | |------------|---------------|---------------------| | rate_limit_error (Rate limit reached...) | Too many requests/tokens per minute for your tier | Yes — back off and retry | | insufficient_quota (You exceeded your current quota...) | Your account has no billing headroom at all | No — fix billing first |

If your error text mentions "plan and billing details," stop retrying.

Why it hits people who are "already paying"

The most common confusion: a ChatGPT Plus/Pro subscription is not API credit. The consumer subscription and the API platform are separate billing systems. A brand-new API key on an account that has never added a payment method or prepaid credits gets insufficient_quota on its very first request.

Other realistic causes:

• Prepaid credits ran out. API billing for newer accounts is prepaid; when the balance hits zero, every request 429s until you top up.
• You hit your own hard limit. A monthly usage cap set in the billing settings acts as a hard stop.
• The free trial grant expired. Old trial credits have expiry dates; the account works for weeks, then suddenly doesn't.
• Wrong organization/project. Keys are scoped — a key created under an org or project with no billing attached fails even if another org on the same login has credit. Check which org the failing key belongs to.

The fix

1. Open the OpenAI platform billing page (platform.openai.com → Settings → Billing) for the org/project the failing key belongs to.
2. Add a payment method or purchase prepaid credits; if a usage limit is set, confirm it is above current usage.
3. Wait a few minutes — quota changes are not always instant.
4. Retest with a minimal request before unleashing your agent again:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.2","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'

In coding agents

In Codex CLI, Cursor with a personal key, or any OpenAI-compatible tool, this error usually surfaces mid-session as a wall of failed retries. Two agent-specific notes:

• Don't debug your base URL. If requests were working and suddenly all return this exact string, your endpoint config is fine — it's the account.
• Long agent sessions drain prepaid balances faster than people expect, because tool-calling loops replay growing context on every step. A session that costs cents at the start costs multiples of that per step near the end.

Prevention

• Set a soft alert threshold in billing settings below your hard limit, so you get an email before the hard stop.
• For team/agent workloads, treat quota exhaustion as a distinct failure mode from rate limiting in your retry logic: insufficient_quota → alert and halt; rate_limit_error → backoff.
• If one provider account going dry should not stop your whole coding session, that is an argument for not hard-wiring a single provider: a router with multiple upstreams can fail over instead of failing — what a router API should handle for you.

Part of the LLM API Error Reference — errors indexed by their exact strings.