Codex CLI: stream disconnected before completion
Two messages come out of Codex for what looks like one problem:
stream disconnected before completion
stream error: exceeded retry limit, last status: 429 Too Many RequestsThey are not the same failure. The first says the connection dropped in the middle of a response. The second says Codex retried, kept failing, and gave up — and the status code at the end tells you which problem you actually have. A 429, a 401 and a 503 share a wrapper and nothing else.
https://aicomp.ai/v1).
Create one free →
Read the status code, then the quota
exceeded retry limit, last status: 429 is usually read as "you ran out of quota". Often true And often not. There is a well-documented pattern of Codex returning 429 while usage is almost untouched: one report on CLI 0.104.0 shows the error arriving with 99% of the 5-hour limit available, 96% of the weekly limit available, and every model-specific limit near full. Two more reports describe the same thing near the end of a window with plenty left.
So check usage before you change anything:
codex
# then inside the session:
/usageIf /usage says you have headroom and the 429 keeps arriving, you are looking at a backend fault, not your account. Waiting a few minutes is more productive than rewriting your config.
The three status codes
| Last status | What it means | What helps |
|---|---|---|
429 Too Many Requests | Too many requests — or a backend fault that reports as one | Check /usage; serialise parallel runs; back off |
401 Unauthorized | Credentials rejected. Retrying could never have worked | codex login, check for invalid_grant: Grant not found |
503 Service Unavailable | Provider down or degraded. Nothing on your machine fixes it | Check provider status and wait |
The 401 case is worth separating because it looks identical in the wrapper. A revoked or expired grant is the usual cause, and no amount of backoff will fix it.
Why the connection drops mid-stream
stream disconnected before completion means the connection was dropped rather than refused. Work through it in this order:
A proxy or VPN cutting long-lived streaming connections. This is the most common cause, and it is common precisely because agent responses stream for minutes at a time while idle-connection timeouts on proxies are measured in seconds. A plain chat request through the same proxy succeeds; long agentic runs fail. That difference is the tell.
Aggressive network timeouts in the same family, corporate networks that terminate idle SSE connections.
Provider-side instability, if the two above are clean.
Model output hitting a max-token ceiling, which truncates rather than drops, but presents similarly.
To confirm it is a timeout and not a quota problem, run one short request. If short requests always succeed and long runs always die, it is the connection, not your budget.
The budget facts that surprise people
Local and cloud share one pool. CLI runs, the IDE extension and cloud sessions draw from the same budget. There is no separate local allowance to fall back on.
Agentic runs cost differently than chat. An agent reads a large part of a codebase before it writes anything, and session start-up context loading counts. Running three agents in parallel costs roughly three times as much. If you moved from chat to agentic work and started hitting limits, that is the reason (not a bug).
On a third-party backend, the limits are that provider's. This is the one that matters if you have pointed base_url at a gateway instead of OpenAI: the rate limits, the quotas and the retry semantics all come from whoever is serving the endpoint. The error text Codex shows you is written for OpenAI's limits and does not always surface a third-party 429 clearly, which is a large part of why this error is confusing in that setup.
What actually reduces the frequency
Check /usage first, every time, it is the only thing that separates "out of quota" from "something is wrong".
Do not run parallel agents when you are near the cap; three agents burn budget three times as fast.
Keep the CLI current (retry and backoff behaviour has changed across releases), and early versions crashed outright on a 429 rather than degrading.
Scope prompts. "Refactor the whole repo" loads far more context than a targeted request, and context is what turns into request rate.
If you are on a gateway, read that provider's limits rather than assuming OpenAI's, and remember that a rate limit is often per model, not per account — routing the mechanical slice to a model with headroom takes pressure off the one you are hitting.
FAQ
FAQ
Does a 429 always mean I am out of quota?
No. There are multiple reports of Codex returning exceeded retry limit, last status: 429 while /usage shows nearly the full limit available. Check usage before assuming you are rate limited, if there is headroom, it is more likely a backend fault and waiting is the productive response.
Why do short requests work but long agent runs disconnect?
Because agent responses stream for minutes, and proxies and VPNs terminate long-lived idle connections much sooner. A plain chat request finishes inside the timeout and succeeds. That contrast identifies a timeout rather than a quota problem.
Do local CLI runs and cloud sessions share the same limit?
Yes. CLI, IDE extension and cloud sessions draw from one budget pool. There is no separate local allowance, so switching clients does not buy you more quota.
What does `exceeded retry limit, last status: 401` mean?
That your credentials were rejected, and retrying could never have helped. An expired or revoked grant is the usual cause. If you see invalid_grant: Grant not found alongside it, that is the same family. Re-authenticate with codex login.
I point Codex at a gateway, not OpenAI. Whose limits apply?
The gateway's. Rate limits, quotas and retry semantics all come from whoever serves the endpoint, and Codex's error text is written for OpenAI's limits, so a third-party 429 is not always surfaced clearly. Check the provider's documented limits instead of inferring them from the message.
Is running agents in parallel worth it near the cap?
No. An agent reads a large part of the codebase before writing, so three parallel agents cost roughly three times as much and will reach the cap three times as fast. Serialise near the limit.
Related
- Codex CLI with a custom endpoint —
config.toml,wire_api, and why 0.122+ rejectschat - Cursor 429 rate limit — the same status code in an editor-shaped loop
- Model fallback chain — routing around a model that is unavailable
- Coding agent cost per month — what an agentic workload actually costs
- OpenAI-compatible error codes — what each status means across tools
- Model price index — check which models have headroom in your budget