OpenAI returns HTTP 429 with error.type insufficient_quota when the organization or project has no billing capacity left—prepaid credits are exhausted or an enforced spend or usage limit was reached—so retrying does not help until credits or limits change.
Why does this error happen?
- error.code credit_balance_exhausted: the organization has no prepaid credits remaining (the API is prepaid; an expired trial grant or a failed auto-recharge leaves the balance at zero even with a card on file).
- error.code organization_spend_limit_exceeded or project_spend_limit_exceeded: an enforced spend limit on the organization or the project was reached.
- error.code organization_usage_limit_exceeded: the organization reached the usage limit OpenAI assigned to it.
- The key belongs to a different project or organization than the one whose billing you checked.
How do you diagnose it?
- Read error.type and error.code from the JSON body: insufficient_quota is a billing state, not the per-minute rate_limit_exceeded error that shares the 429 status.
- Open the organization and project billing pages and compare the credit balance, auto-recharge state, project spend limit and organization spend or usage limit against the code you received.
- Confirm which project the API key belongs to, and record the request ID and UTC timestamp without logging the key.
{
"error": {
"type": "insufficient_quota",
"code": "credit_balance_exhausted",
"message": "<billing message from OpenAI>"
}
}How do you fix it?
- credit_balance_exhausted: add prepaid credits or enable auto-recharge.
- organization_spend_limit_exceeded / project_spend_limit_exceeded: raise or remove the enforced spend limit in organization or project settings; organization_usage_limit_exceeded: request a higher approved usage limit or contact support.
- Do not retry with backoff: OpenAI states that retrying billing, spend or quota errors will not restore access until the credits or limits are updated.
How do you prevent it from recurring?
Turn the confirmed cause of insufficient_quota into an observable boundary for OpenAI API. Track the relevant request count, token volume, payload size, execution time, connection pressure, billing state, or upstream health before it reaches the documented failure condition. Preserve the platform request ID and timestamp so future incidents can be correlated without logging sensitive payloads.
Test the fix under representative concurrency and failure injection, not only with one successful request. Alert on remaining headroom and repeated retries, and keep the linked limit page and official error source with the runbook so responders can distinguish a configuration problem from temporary service pressure or account state.