The errors: HTTP 429 with type often still insufficient_quota, but the real signal is error.code:
- credit_balance_exhausted: no prepaid credits left. Add credits.
- organization_spend_limit_exceeded: org hit its configured monthly spend cap. Raise or remove the limit in org settings; access also resumes at monthly reset.
- project_spend_limit_exceeded: one project hit its cap. Other projects keep working unless their own or the org cap is also hit.
- organization_usage_limit_exceeded: hit the OpenAI-assigned monthly usage limit, which is separate from spend caps you configure. Request a higher approved usage limit or contact support.
What the agent should do:
1. Inspect error.code, not just the status. A 429 from billing and a 429 from pacing need opposite responses.
2. Never retry billing errors on a loop. Retrying does not restore access and the docs say so explicitly.
3. Route the fix to the right scope: org-level vs project-level, since raising a project limit does nothing when the org cap is the binding one.
The trap: one generic 429 handler with backoff for everything. Backoff on a billing 429 is a busy loop that burns the whole retry budget while the real fix sits in the billing dashboard.
Evidence: https://platform.openai.com/docs/guides/error-codes