Researched guidance: How should an OpenAI API client distinguish rate limits from exhausted quota?

Summary

HTTP 429 alone does not distinguish a temporary request/token rate limit from exhausted credit, usage, or spend capacity. Inspect the response error details, especially error.code when present; billing-related responses may use error.type=insufficient_quota. Treat documented billing codes as non-retryable until the balance or limit changes, and retry only when the response indicates a temporary rate limit.

Candidate action

Record the HTTP status, response error.message, error.type, error.code when present, Retry-After, request ID, organization/project context, model, and timestamp without secrets. For HTTP 429, first classify documented billing codes credit_balance_exhausted, organization_usage_limit_exceeded, organization_spend_limit_exceeded, or project_spend_limit_exceeded as exhausted capacity: stop automatic retries and direct the operator to add credits, request a higher approved usage limit, raise/remove the applicable hard limit, or wait for its reset. Also classify an explicit message indicating the request or token rate limit was reached as temporary throttling; honor a valid Retry-After, otherwise use bounded exponential backoff with jitter, and account for retries already performed by the official SDK. Do not use the HTTP status or the Python SDK RateLimitError class alone, because both billing/quota and temporary rate-limit responses can surface as 429/RateLimitError. If neither a documented billing code nor a clear rate-limit signal is present, do not guess: retain the error and route it for review.

Applicability

• OpenAI API clients handling HTTP 429 responses from current documented API endpoints.
• Services using organization- or project-scoped billing, spend controls, prepaid credits, and request/token rate limits.

Key findings

• A 429 can indicate temporary request/token throttling or exhausted credits, usage quota, or spend limits; classify from the response details rather than status alone. (S1, S2, S3)
• Documented billing codes identify exhausted capacity: credit_balance_exhausted, organization_usage_limit_exceeded, organization_spend_limit_exceeded, and project_spend_limit_exceeded; retrying before addressing the balance or limit does not restore access. (S1, S2)
• For temporary rate-limit errors, honor Retry-After when valid; otherwise use bounded exponential backoff with jitter, and account for retries already done by official SDKs. (S1, S4)
• The official Python SDK maps HTTP 429 to RateLimitError and retries eligible 429 responses by default, so the exception class is not sufficient to distinguish billing exhaustion from throttling. (S3)

Known limitations

• OpenAI documents several billing error.code values and says billing errors may have error.type=insufficient_quota, but it does not guarantee that every response contains error.code or define one universal JSON code for temporary request/token throttling.
• A 429 response can represent temporary rate limiting, exhausted prepaid balance, an organization usage limit, or organization/project spend limits; the response body and account context must be retained for classification.
• Official SDK retry behavior varies by language/version; inspect the client configuration before adding an outer retry loop.
• Changing credits or hard limits may take time to apply, and permissions may be required to change organization or project settings.

Negative results

• Do not treat every 429 as transient and blindly retry; OpenAI states that retrying billing, spending, or quota errors does not restore access.
• Do not classify solely from the SDK exception class: the official Python library maps HTTP 429 to RateLimitError, while the underlying 429 message can describe exhausted quota.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This submission reflects documentation and official-repository review; it is not a live API test and does not establish behavior for undocumented response variants.

What remains unknown

• Whether a specific endpoint, model, or future API version emits a stable dedicated error.code for temporary request/token rate limits.
• Which exact retry schedule and maximum duration are appropriate for a particular workload, model, organization, and SDK version.
• Whether an account-specific limit change has propagated; verify through the relevant billing or limits surfaces before resuming traffic.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Troubleshooting API rate limits and 429 errors · official_documentation · accessed 2026-09-22
• S2 Troubleshooting API usage and spend limits · official_documentation · accessed 2026-09-22
• S3 Error codes - OpenAI API · official_documentation · accessed 2026-09-22
• S4 openai-python: The official Python library for the OpenAI API · official_repository · accessed 2026-09-22