Skip to content

feat: add InsufficientQuotaError for insufficient_quota 429 responses#3042

Open
crawfordxx wants to merge 1 commit intoopenai:mainfrom
crawfordxx:feat-insufficient-quota-error
Open

feat: add InsufficientQuotaError for insufficient_quota 429 responses#3042
crawfordxx wants to merge 1 commit intoopenai:mainfrom
crawfordxx:feat-insufficient-quota-error

Conversation

@crawfordxx
Copy link
Copy Markdown

  • I understand that this repository is auto-generated and my pull request may not be merged

Changes being requested

This PR adds a new InsufficientQuotaError exception class that subclasses RateLimitError, enabling users to distinguish between temporary rate limits and quota exhaustion when handling 429 responses.

Currently, both rate-limiting and insufficient-quota errors raise RateLimitError, but they require very different handling:

  • Rate limit: retry after a delay
  • Insufficient quota: switch to a backup API key, alert the user, etc.

What changed

  • src/openai/_exceptions.py: Added InsufficientQuotaError(RateLimitError) with status_code = 429
  • src/openai/_client.py: Updated _make_status_error in both OpenAI and AsyncOpenAI to check if the error code is "insufficient_quota" before falling back to RateLimitError
  • src/openai/__init__.py: Exported InsufficientQuotaError

Backward compatibility

InsufficientQuotaError extends RateLimitError, so existing except RateLimitError blocks will continue to catch both error types. Users who want to handle quota exhaustion differently can now catch InsufficientQuotaError specifically:

try:
    client.chat.completions.create(...)
except openai.InsufficientQuotaError:
    switch_to_backup_key()
except openai.RateLimitError:
    time.sleep(retry_delay)

Additional context & links

Closes #1671

Add a new InsufficientQuotaError exception that subclasses RateLimitError,
allowing users to distinguish between temporary rate limits and quota
exhaustion (insufficient_quota error code). This is backward-compatible
since InsufficientQuotaError extends RateLimitError.

Closes openai#1671
@crawfordxx crawfordxx requested a review from a team as a code owner April 1, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

insufficient_quota in _exceptions.py

1 participant