Codex Rate Limit Errors: Causes and Fixes

A Codex “rate limit” error is four different problems wearing one message, and the fix depends entirely on which meter you hit. The rolling 5-hour window clears on its own schedule and ignores retries. The weekly cap on some plans means days, not hours. A drained credit balance stops on-demand top-up work mid-run. And a 429 on an API-key session is a per-minute throttle that backoff genuinely fixes. Diagnose first, with /status; the fix follows from the diagnosis.

Step one: ask /status

Inside the CLI, /status shows your auth mode, current usage, and the reset times for both the short window and any weekly component. That readout is the ground truth for your account, which matters because plan limits vary by plan and model and shift over time. We deliberately quote no message counts here; the numbers drift, and OpenAI publishes the live ones at developers.openai.com/codex/pricing. The system behind the meters, windows, weekly caps, the shared pool across CLI and IDE and cloud tasks, is mapped in Codex usage limits, explained.

Decoding the error

What you see	Which meter	When it clears	What actually helps
A usage-limit message with a try-again time measured in hours	Rolling 5-hour window	Roughly five hours after the usage that filled it	Wait, pace, lower reasoning effort, or switch lanes
The message points at a weekly limit, with a days-scale wait	Weekly cap (some plans, notably Plus and Pro)	On its seven-day cycle	Pacing, a second owned account, credits, or an API lane
Credit balance at zero while continuing past a limit	On-demand credits drained	When you buy more, or your window resets	Close parallel sessions; reconsider credits vs lanes
HTTP 429 / rate_limit_exceeded on an API-key session	Per-minute API throttle for your tier	Seconds to a minute	Exponential backoff, smaller bursts, higher API tier

The first three are plan-lane problems: they meter work, including reasoning time and retries, against your subscription’s windows. The fourth is an API-lane problem and the only one where a retry loop is the right tool.

Fixes by meter

The 5-hour window

The window is a pace limiter, and heavy agent sessions fill it fastest because planning, tool calls, and failed attempts all meter as work. Quick relief: close parallel sessions you forgot about, drop reasoning effort for routine tasks, and let the rolling window shed your oldest usage. If you hit it most days, the deeper mechanics in Codex’s 5-hour window are worth ten minutes.

The weekly cap

The weekly cap is the one that turns a limit from an annoyance into a schedule problem, because community reports consistently show heavy agent use can meet it within a day or two, followed by a long wait. Pacing helps; so does shifting bulk work to early in the cycle. When it recurs monthly, the structural options are a higher tier, a second account you own, or an overflow lane, compared honestly in the weekly limit guide.

Drained credits

On-demand credits are a metered top-up for Plus and Pro, and they drain by work performed, which on agent workloads is faster than most buyers expect. If a credit balance keeps rescuing you, you are paying metered rates on top of a flat plan every month. The arithmetic on when credits beat a second account, and when they do not, is in Codex credits, explained.

API-key 429s

A 429 from an API-key session has nothing to do with plan windows. It is a per-minute throttle, and the fix has been standard for a decade: back off exponentially, add jitter, and smooth bursts.

A retry that knows the difference

Most retry wrappers treat every failure as transient, which turns a filled window into hours of pointless API calls. This one stops when retrying cannot help:

#!/usr/bin/env bash
# codex-retry.sh "prompt": retry transient failures, stop on exhausted windows
set -u
for delay in 5 15 45 120; do
  if out=$(codex exec --sandbox read-only "$1" 2>&1); then
    printf '%s\n' "$out"
    exit 0
  fi
  if grep -qiE "usage limit|weekly limit" <<<"$out"; then
    echo "plan window exhausted: wait for the reset or switch lanes" >&2
    exit 75 # EX_TEMPFAIL: let the caller reschedule instead of hammering
  fi
  sleep "$delay"
done
echo "still failing after retries" >&2
exit 1

A retry loop cannot refill a window; only a reset or another lane can. Exit code 75 tells the calling scheduler to try again later rather than escalate, which is the polite behavior for a limit that will fix itself.

The durable fix: give overflow a lane

Every fix above manages the symptom. The durable fix changes the topology: when one meter fills, the request should go somewhere else instead of failing. Two lanes exist for that. A second ChatGPT account you own brings independent windows for a flat $20 or $100 a month, with the boundary that each account must genuinely be yours, since OpenAI’s terms prohibit sharing accounts between people. Your own OpenAI API key brings a lane with no windows at all, just a meter.

Switching lanes by hand at 2 a.m. is not a system, so we built the ordering into Codex Hosted: requests run on your primary account’s plan, fall back to a second connected account when a window fills, then to your API key, and return to the subscription lane at reset. The request log names the lane that served each call, so a rate-limit error becomes a line item instead of an outage. The full failover behavior is in what happens when you hit your Codex usage limit.

If limit errors are a weekly event rather than a curiosity, size the problem before buying anything: the calculator maps your actual workload to plan tiers and shows what overflow would cost on each lane.