OpenAI insufficient_quota: meaning, cause, and fix

Why it happens

OpenAI uses prepaid credit and optional budget caps. When the usable balance reaches zero or a cap is reached, the API stops serving requests. Common causes include exhausted credits, a project budget limit, or expired trial credit.

The key can also belong to a project whose quota is exhausted while another project still has credit. Check the project attached to the credential rather than assuming that quota is shared across all projects in the account.

The error you'll see

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

HTTP status: 429. That status is the trap — your retry middleware sees 429 and politely backs off, then fails again, forever. The body, not the status, tells you which 429 you have.

Handle quota and rate-limit errors separately

Split the two 429s at the handler level. Quota failures go to an alert; rate limits go to backoff:

# Python — route the two 429s differently
from openai import OpenAI, RateLimitError

client = OpenAI()
try:
    r = client.chat.completions.create(model="gpt-5", messages=msgs)
except RateLimitError as e:
    if "insufficient_quota" in str(e):
        alert_oncall("OpenAI billing exhausted — requests halted")
        raise            # retrying is pointless
    sleep_with_backoff() # a real rate limit — this one heals itself

Prevention

Set a usage alert below your cap, not at it. You want the email before production feels anything. Give each project its own budget so one runaway batch job can't starve the rest. And if quota keeps evaporating faster than planned, the bill itself is the bug: route bulk traffic to a cheaper tier instead of feeding everything to your most expensive model.