Skip to content

feat: add InsufficientQuotaError for insufficient_quota 429 responses #3507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pctablet505 wants to merge 4 commits into
base: main
Choose a base branch
from
+376 −1
Open

feat: add InsufficientQuotaError for insufficient_quota 429 responses #3507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2a8433e
feat: add InsufficientQuotaError for insufficient_quota 429 responses
pctablet505 Jul 15, 2026
036eb86
fix: don't retry insufficient_quota 429 responses
pctablet505 Jul 19, 2026
63a1951
fix: read response body before retry classification for streamed 429s
pctablet505 Aug 4, 2026
1376bd6
fix: don't let a failed body read block retry classification
pctablet505 Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/openai/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
AuthenticationError,
InternalServerError,
PermissionDeniedError,
InsufficientQuotaError,
LengthFinishReasonError,
WebSocketQueueFullError,
UnprocessableEntityError,
Expand Down Expand Up @@ -69,6 +70,7 @@
"ConflictError",
"UnprocessableEntityError",
"RateLimitError",
"InsufficientQuotaError",
"InternalServerError",
"LengthFinishReasonError",
"ContentFilterFinishReasonError",
Expand Down
38 changes: 38 additions & 0 deletions src/openai/_base_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -845,6 +845,18 @@ def _should_retry(self, response: httpx2.Response) -> bool:

# Retry on rate limits.
if response.status_code == 429:
# An `insufficient_quota` error means the account has run out of
# quota; retrying will not help, so don't burn the retry budget
# on a request that is guaranteed to fail again.
try:
body = response.json()

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid retrying streamed quota errors

Fresh evidence after the retry fix: for stream=True/.with_streaming_response calls, _base_client.request() sends the request with streaming enabled, so the 429 body has not been read when this line calls response.json(); httpx raises ResponseNotRead, the broad except turns the body into None, and the code falls through to retry. Streaming chat/responses requests that receive code="insufficient_quota" will therefore still burn max_retries before raising, unlike the non-streaming path covered by the new tests.

Useful? React with 👍 / 👎.

except Exception:
body = None
data = body.get("error", body) if is_mapping(body) else body
if is_mapping(data) and data.get("code") == "insufficient_quota":
log.debug("Not retrying as the error code is `insufficient_quota`")
return False

log.debug("Retrying due to status code %i", response.status_code)
return True

Expand Down Expand Up @@ -1122,6 +1134,19 @@ def request(
except status_exceptions() as err: # thrown on 4xx and 5xx status code
log.debug("Encountered an HTTP status error: %i", response.status_code)

# The retry classification below may inspect the response body (e.g. to
# detect `insufficient_quota`), so make sure it has been read first. For
# `stream=True` requests the body is not read automatically and accessing
# it before this point raises `httpx.ResponseNotRead`. Reading can itself
# fail (e.g. a dropped connection mid-stream) for errors that are still
# retriable on status/headers alone, so a read failure here must not stop
# `_should_retry` from running.
if not err.response.is_closed:
try:
err.response.read()
Comment on lines +1144 to +1146

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restrict eager error-body reads to quota responses

Fresh evidence after the catch fix is that this unconditional read still runs before retry classification for every streamed HTTP error, although only 429 quota classification needs the body. A streamed 408, 409, or 5xx response whose body stalls now waits for the read timeout—600 seconds by default, potentially once per attempt—before _should_retry() can retry from the already-available status and headers; catching the eventual exception does not avoid that delay. Gate the eager read to 429 responses in both the synchronous and asynchronous paths.

Useful? React with 👍 / 👎.

except Exception:
pass

if remaining_retries > 0 and self._should_retry(err.response):
err.response.close()
self._sleep_for_retry(
Expand Down Expand Up @@ -1745,6 +1770,19 @@ async def request(
except status_exceptions() as err: # thrown on 4xx and 5xx status code
log.debug("Encountered an HTTP status error: %i", response.status_code)

# The retry classification below may inspect the response body (e.g. to
# detect `insufficient_quota`), so make sure it has been read first. For
# `stream=True` requests the body is not read automatically and accessing
# it before this point raises `httpx.ResponseNotRead`. Reading can itself
# fail (e.g. a dropped connection mid-stream) for errors that are still
# retriable on status/headers alone, so a read failure here must not stop
# `_should_retry` from running.
if not err.response.is_closed:
try:
await err.response.aread()
except Exception:
pass

if remaining_retries > 0 and self._should_retry(err.response):
await err.response.aclose()
await self._sleep_for_retry(
Expand Down
4 changes: 4 additions & 0 deletions src/openai/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -792,6 +792,8 @@ def _make_status_error(
return _exceptions.UnprocessableEntityError(err_msg, response=response, body=data)

if response.status_code == 429:
if is_mapping(data) and data.get("code") == "insufficient_quota":
return _exceptions.InsufficientQuotaError(err_msg, response=response, body=data)
Comment on lines 794 to +796

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Skip retries for insufficient_quota responses

With the default max_retries, _base_client calls _should_retry() and retries every 429 before _make_status_error() is reached, so this new branch only runs after the retry budget is exhausted; the async path has the same flow. For deterministic code="insufficient_quota" responses this still sends multiple doomed requests and delays surfacing the non-retryable quota error, so the quota code needs to be classified before retrying or handled in _should_retry.

Useful? React with 👍 / 👎.

return _exceptions.RateLimitError(err_msg, response=response, body=data)

if response.status_code >= 500:
Expand Down Expand Up @@ -1488,6 +1490,8 @@ def _make_status_error(
return _exceptions.UnprocessableEntityError(err_msg, response=response, body=data)

if response.status_code == 429:
if is_mapping(data) and data.get("code") == "insufficient_quota":
return _exceptions.InsufficientQuotaError(err_msg, response=response, body=data)
return _exceptions.RateLimitError(err_msg, response=response, body=data)

if response.status_code >= 500:
Expand Down
5 changes: 5 additions & 0 deletions src/openai/_exceptions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
"ConflictError",
"UnprocessableEntityError",
"RateLimitError",
"InsufficientQuotaError",
"InternalServerError",
"LengthFinishReasonError",
"ContentFilterFinishReasonError",
Expand Down Expand Up @@ -157,6 +158,10 @@ class RateLimitError(APIStatusError):
status_code: Literal[429] = 429 # pyright: ignore[reportIncompatibleVariableOverride]


class InsufficientQuotaError(RateLimitError):
status_code: Literal[429] = 429 # pyright: ignore[reportIncompatibleVariableOverride]


class InternalServerError(APIStatusError):
pass

Expand Down
Loading