A troubleshooting guide
Is Codex down, or is it you?
Two things settle it in about a minute: the right row on OpenAI’s status page, and the exact words of the error the Codex CLI shows you. Here is where to look, and what each error means.
Check in a minute
1
Find the CLI on OpenAI's status page
status.openai.com covers all of OpenAI. The Codex CLI is the “CLI” row in the Codex group, next to Codex Web, the Codex API and the VS Code extension. Trouble signing in shows on the “Login” rows instead.
2
Read the error's exact words
Codex prints the cause after a red square. High demand or a model at capacity is OpenAI’s side; a usage limit, an expired sign-in or a failed connection is yours. The table below sorts each one.
3
Run codex doctor
codex doctor checks your install, config and sign-in, your proxy settings, and whether Codex can reach OpenAI from this Mac. If it passes and the status page is clear, look at your plan’s limits next.
The error says whose side it’s on
Codex already retries server errors and dropped answers before it shows you anything, and keeps trying when the connection drops, so a short blip never reaches you. What does reach you sorts into three kinds.
| What Codex says | Whose side | What to do |
|---|---|---|
We’re currently experiencing high demand, which may cause temporary errors. | Whose side: OpenAI's | What Codex shows for a server error. It has already retried by the time you see this; wait a little and send again. |
Selected model is at capacity. Please try a different model. | Whose side: OpenAI's | That one model is full right now. Switch with /model, or wait and try again. |
You’ve hit your usage limit. | Whose side: Yours | Your plan’s allowance is used up, and the message ends with the time it resets. Nothing is down. /status shows what’s left of your limits and when each resets, and the usage dashboard has the rest. |
Your workspace is out of credits. | Whose side: Yours | On a workspace plan, the shared credits ran out. Add credits, or ask the workspace owner to. A spend cap reads “You hit your spend cap” and needs the same person. |
Your access token could not be refreshed… Please log out and sign in again. | Whose side: Yours | Your saved sign-in expired, was revoked, or was replaced by another account. Run codex logout, then codex login. |
Quota exceeded. Check your plan and billing details. | Whose side: Yours | Shown when you sign in with an API key: the key's billing or spend limit is reached. Fix it in your OpenAI account. |
Connection failed | Whose side: Yours | Codex couldn’t reach OpenAI from your Mac: your network, a VPN or a proxy. While it waits, the status line reads “Reconnecting... waiting for network”, and it keeps trying on its own. codex doctor checks the proxy and the connection. |
Access blocked by Cloudflare. | Whose side: Yours | OpenAI's network refused the connection, which Codex says usually means a restricted region. A VPN exit in another country is the common cause. |
stream disconnected before completion | Whose side: Could be either | The answer stopped partway. Codex retries this itself, showing “Reconnecting... 1/5”; if every retry fails, check the status page, then your connection. |
exceeded retry limit, last status: … | Whose side: Could be either | Codex gave up after its retries. The status after it says why: a 5xx is OpenAI's side; a 429 is a rate limit on your account or key. |
Status page clear and the error keeps coming? Run codex login status to see how you’re signed in, codex doctor for the rest, and /feedback inside Codex to send your logs to OpenAI.
Or let the menu bar check for you
Hear about an outage before you start debugging
Perch reads status.openai.com for you once you’ve used Codex on your Mac: often while a session is open, less often between them. It watches the Codex CLI’s own row, not the rest of OpenAI. When that row shows an outage, a red banner in the menu bar dropdown says so and links to OpenAI’s incident. A slowdown or maintenance shows as a small icon beside Codex’s usage, and every open problem is listed in Settings → General → Integrations.
It shows what OpenAI has posted, so in the first minutes of an outage the error in your terminal can arrive before the incident does. For that gap, the dropdown also notes when three of your turns fail on an overloaded or internal server error within five minutes: something seen on this Mac, not a report from OpenAI. Your own limits are a separate signal: when Codex reports a usage limit, its row turns yellow and says “Rate limited”, and Perch sends the rate-limit alert. The same pass tells you when your Codex is out of date, with the command to update it. How Perch watches agent health.
Questions
Codex outages, answered
Is Codex down right now?
Which row on OpenAI's status page covers the Codex CLI?
Where do I see how much Codex usage I have left?
Does Codex retry on its own?
What does codex doctor check?
The same guide for Claude Code, Amp, Devin and Droid.