DEV Community

Anup Karanjkar
Anup Karanjkar

Posted on Originally published at wowhow.cloud

Codex 429 Exceeded Retry Limit: Causes and Fixes

"exceeded retry limit, last status: 429 Too Many Requests" is a rate-limit or capacity error, not a usage-limit error, and in the most common path the Codex client did not retry the request at all. An OpenAI maintainer said so on openai/codex#22122 on May 11, 2026: "This isn't a usage limit error. It's a rate limit error designed to prevent DDoS attacks." The wording comes from one error type in the Rust source, and at least four different situations produce it: a burst of requests (often subagents), an account-wide Retry-After window, a server-side incident at OpenAI, and, for API-key users, an ordinary requests-per-minute or tokens-per-minute limit. Two of them cannot be fixed from your machine. Below: what the message means, a triage table, fixes per cause, backoff for API-key users, and what the CLI retries, read from the openai/codex source at commit f1ebc7b3 on November 16, 2026.

How this was checked: WOWHOW fetched the five issues, the codex-rs retry source, OpenAI's rate limits guide and the Codex pricing page on November 16, 2026. Every number links to its line. The latest tagged release that day was 0.169.0 (November 13, 2026).

TL;DR

  • The text is the Display output of RetryLimitReachedError in protocol/src/error.rs. It fires for any HTTP 429 whose body is not a recognised usage or quota error.

  • The provider retry policy sets retry_429: false, so the HTTP layer does not retry a 429 even once. The name "exceeded retry limit" is misleading, and #30471 (filed June 28, 2026, still open) asks OpenAI to rename it.

  • If the 429 carries a Retry-After header, the turn-level loop does wait and retry, up to 5 times by default, sleeping until the server's deadline. Over WebSockets, release builds hide the first retry, which is why #58883 saw sessions sit on "Working" for 400 seconds.

  • Two documented cases were OpenAI incidents: #9148 (January 13, 2026) and #26034 (June 3, 2026). The maintainer wrote "This is not a client-side issue."

  • Run /status first. If your meters are not full, this is not the usage limit, and credits will not clear it.

What the message means

Codex talks to the Responses endpoint. When that endpoint answers HTTP 429, api_bridge.rs inspects the JSON body. Three body shapes get their own error and their own message: usage_limit_reached becomes a usage-limit error with the reset time and the active window, usage_not_included says your plan does not include Codex, and insufficient_quota or the spend-limit codes (organization_spend_limit_exceeded, project_spend_limit_exceeded, credit_balance_exhausted) become a quota error. Everything else that arrives as a 429 falls through to CodexErr::RetryLimit, which carries only the status and the request id. The body text, the Retry-After value and the x-codex-* headers are dropped at that point, a complaint #58883 makes in detail.

So the message tells you the server said 429, that the body was not a usage or quota error, and the request id. It hides why. That is why the triage below leans on /status, the status page and your own logs instead of the error text.

The "retry limit" part is a naming accident. The same error type is used when the HTTP layer really exhausts its retries on a 5xx, where the displayed status is 500 (api_bridge.rs lines 315-318). With last status: 429, the HTTP layer made one attempt. model-provider-info/src/lib.rs builds every provider's policy with retry_429: false, retry_5xx: true and retry_transport: true, and codex-client/src/retry.rs only retries a 429 when that flag is true. The flag is not exposed in config.toml.

60-second triage

Work the table top to bottom. The first three checks need no log files: /status, the usage dashboard and status.openai.com.

Symptom Likely cause Fix

| Every message fails, including a one-line prompt. /status shows plenty of usage left. The status page lists a Codex or API incident. | Server-side incident. #9148 (Jan 13, 2026) and #26034 (Jun 3, 2026) were both closed as OpenAI-side fixes. | Wait. The maintainer on #26034 said there was "no need to upload logs or provide /feedback" during the incident. |

| The error appears when several subagents or parallel sessions run, and goes away when you run one thing at a time. | Request-rate throttle on the Responses endpoint. The maintainer's diagnosis on #22122 (May 11, 2026). | Cut concurrency. Codex caps subagents at 6 by default, per the same comment; stay at or below it, and close idle sessions. |

| A session sits on "Working" for minutes with nothing on screen. ~/.codex/logs_2.sqlite shows retrying sampling request (1/5 in 300s…) with a 429. | Account-wide Retry-After window, as in #58883 (Nov 2, 2026, CLI 0.166.0). Several sessions received the same deadline. | Let the deadline pass. Sending a new message restarts the hidden wait (#58883, point 4). The maintainer said a clearer message is coming in an upcoming release (Nov 3, 2026). |

| The error names a usage limit or a reset time, and /status shows a full 5-hour or weekly meter. | Usage limit, which is a different error type. You are not looking at this bug. | Wait for the reset, buy credits (Plus and Pro can, per the pricing page), or run the task with an API key at API rates. |

| You use an API key. The 429 response carries x-ratelimit-* headers, or the body code is slow_down. | Requests-per-minute or tokens-per-minute limit on your organization or project, or a ramp-rate limit, per the rate limits guide. | Follow Retry-After, back off with jitter, and raise the limit through your usage tier. See the backoff section below. |

| You use an API key and the body code is organization_spend_limit_exceeded, project_spend_limit_exceeded or insufficient_quota. | A hard spend cap or empty balance. Codex shows this as a quota error, not "exceeded retry limit". | Raise the cap or add credit. Retrying does nothing. The spend caps guide covers where these limits live. |

Fixes by cause

Incident: do nothing clever

Both incident threads follow the same shape. #9148 (January 13, 2026, CLI 0.80.0, Pro plan) reported the error while "far below my 5h and weekly limits"; the maintainer called it "a service-side issue" and closed it the same day with "We've addressed the underlying cause." #26034 (June 3, 2026, Codex desktop app) drew 40 comments in two days, and the maintainer posted "We have an active incident" twelve minutes after the report. Logging out, reinstalling and removing MCP servers changed nothing for the people who tried them in that thread. When a 429 hits every account at once, check the status page and wait.

Burst: reduce what runs at once

22122 came from a Plus user on the Codex app (version 5.3, May 11, 2026). The maintainer's answer is the clearest statement of this cause on record: too many requests to the responses endpoint in too short a time, with subagents as the usual multiplier, and a default cap of 6 subagents "to prevent this sort of error." If you raised that cap, or run several sessions plus a review job plus a cloud task on one account, you are the burst. Bring it down and stagger parallel work.

Account-wide window: wait it out and keep the logs

58883 is the best-documented case. A Pro Lite account on CLI 0.166.0 saw five requests from two sessions, over six minutes, all receive a Retry-After that resolved to the same second (13:09:11 UTC on November 2, 2026). The weekly meter sat at 46 to 48 percent and no subagents were running. The waits were 69 to 400 seconds, and the TUI showed none of it because release builds suppress the first WebSocket retry notice. The reporter's query shows the hidden waits:

sqlite3 ~/.codex/logs_2.sqlite "select datetime(ts,'unixepoch'), substr(feedback_log_body, instr(feedback_log_body,'retrying'), 120) from logs where target='codex_core::responses_retry' and feedback_log_body like '%429%' order by ts desc limit 10"
Enter fullscreen mode Exit fullscreen mode

If it returns multi-minute delays, do not resend: a new message into a backed-off session "retries at once, gets another 429 with the same deadline, and restarts the hidden wait." Let the deadline pass. If it recurs, upload logs with /feedback and, as the maintainer asked in #9148, "file a new bug with the thread ID."

Usage limit: a different error, a different fix

The pricing page, read November 16, 2026, describes a five-hour period for Plus and Standard Business, says "Pro plans currently have no five-hour limit," and adds that "Weekly limits may also apply." A real usage limit shows a reset time, because the server sends usage_limit_reached. If your meters are full, the options the page lists are to wait, to buy credits on Plus or Pro, or to run "extra local chats using an API key" at standard API rates. The Codex window math post works through how fast each plan burns, and the page's own tips for stretching a window are to trim prompts, shrink AGENTS.md and disable MCP servers you are not using.

API-key users: backoff with jitter

With an API key, the 429 is governed by the rate limits guide. Limits are per organization and project, by model, in requests and tokens per minute. The Retry-After header is "the minimum number of seconds to wait before retrying a temporary rate-limit error." A slow_down 429 "can occur even when your traffic is within its requests-per-minute and tokens-per-minute limits"; it reflects how fast traffic ramped, and the rule of thumb given is no more than a 50 percent increase every 15 minutes once you pass 1 million input tokens per minute. Failed requests still count against the per-minute limit, so a tight retry loop makes the problem worse.

The guide's prescription: follow Retry-After when present and treat it as a minimum, add a small random delay so clients do not retry in lockstep, fall back to exponential backoff with jitter when the header is missing, cap both the attempt count and the total time, and never retry quota or billing errors. The official SDKs already retry eligible 429 and 503 responses, so if you add your own loop, disable the SDK's (max_retries=0 in the Python examples) or the two loops multiply.

The exponential backoff calculator turns those rules into a schedule you can read. Enter the base delay, multiplier, cap and attempt count, compare full, equal and decorrelated jitter, and copy the retry loop in JavaScript, Python, Go or curl. For scale, Codex's own HTTP layer uses a 200 millisecond base, doubling with 10 percent jitter (retry.rs lines 43-52): with the default 4 retries that is roughly 0.2, 0.4, 0.8 and 1.6 seconds, about 3 seconds total, tuned for transient 5xx errors. A rate-limit loop should start near 1 second, cap near 60 and honour the header first, which is what the guide's Tenacity example does with wait_random_exponential(min=1, max=60). The HTTP status code reference covers 429 and 503 semantics.

What the CLI retries, and what it does not

This changes between releases, so everything below is pinned to commit f1ebc7b3 on main, fetched November 16, 2026. There are two retry loops.

Layer Default budget Retries 429? Delay Source

| HTTP request (request_max_retries) | 4, hard cap 100 | No (retry_429: false). Retries 5xx, timeouts and connection errors. | Retry-After if present, else 200 ms doubling with 10% jitter | lib.rs lines 74-82, retry.rs lines 84-118 |

| Response stream (stream_max_retries) | 5, hard cap 100 | Only when the 429 carried Retry-After. Without it the error is terminal. | Sleeps until the server's deadline | error.rs lines 464-473, responses_retry.rs lines 159-185 |

The stream-layer behaviour is newer than #30471 describes. That issue, written against the June 27, 2026 source, found RetryLimit "explicitly non-retryable." At today's HEAD the error is classified RetryPolicy::ServerDirected (error.rs lines 520-522): the retry delay is whatever Retry-After said, and nothing if the header was absent. retry_after.rs accepts the header as whole seconds or an HTTP date and pins the deadline when the response arrived, so passing the error between callers cannot restart the clock. That matches the #58883 logs: one 429 with a 400-second header, one retry, a 400-second sleep.

Four more details explain what you see on screen:

  • Release builds hide the first WebSocket retry. The condition is retry_count > 1 || cfg!(debug_assertions) || !websocket_enabled (responses_retry.rs lines 162-177). From the second retry on, the UI shows "Reconnecting... 2/5".

  • When the stream budget is spent, the client tries to switch from WebSockets to HTTPS, still sleeps until any server deadline, emits "Falling back from WebSockets to HTTPS transport", and resets the retry counter to zero (lines 134-157). A stubborn 429 can therefore take more than five waits to surface.

  • request_max_retries and stream_max_retries are fields on the provider definition (lib.rs lines 209-212), both clamped to 100. Raising them does not make a 429 without Retry-After retryable, because that path never consults them.

  • 30471's requested retry_429 setting does not exist. The flag is still a hard-coded false at line 502, so the only 429 Codex ever waits on is one the server explicitly timed.

Frequently Asked Questions

Is "exceeded retry limit, last status: 429" the same as hitting my Codex usage limit?

No. A usage limit arrives as a usage_limit_reached body and Codex shows it with a reset time. The retry-limit text means the 429 body was something else: a rate limit, a capacity rejection or an incident.

Did Codex actually retry before showing this?

At the HTTP layer, no. The provider policy has retry_429: false at commit f1ebc7b3. At the turn level it retries only if the server sent Retry-After, and then it sleeps until that deadline, up to 5 times by default.

Why does my session show "Working" for minutes with no error?

Over WebSockets in a release build the first retry is not reported, and a Retry-After of several minutes lands on exactly that first retry. #58883 documents waits of 69 to 400 seconds hidden this way. The maintainer said on November 3, 2026 that the message is being improved in an upcoming release.

Will reinstalling, logging out or removing MCP servers fix it?

Not for the incident or account-wide cases; people in #26034 tried all three during the June 3, 2026 incident without effect. Removing MCP servers shrinks each request, which helps usage, not a server-side 429.

What should I include in a bug report?

The request id from the error text, the thread id, your CLI version and plan, and the output of the query above. Upload logs with /feedback; the maintainer asked for a new issue rather than comments on closed ones.

Can I make Codex retry 429s more aggressively from config.toml?

Not today. retry_429 is not a configuration option, and the retry-count settings govern only 5xx, transport and server-timed retries. For API-key automation, put the backoff in your own wrapper, and check whether the Codex daemon is also issuing requests on the same key.

Note: Source citations point at openai/codex commit f1ebc7b3 (main, November 16, 2026); issue quotes were read the same day. Retry behaviour and the error text change often, so re-check the linked lines before relying on them.

Originally published at wowhow.cloud

Top comments (0)