“unexpected status 401 Unauthorized” — what it means in Codex
Codex CLI, app and IDE extension — Codex's own error template, quoted verbatim, plus what users and the Codex team have said about it on the openai/codex tracker. The docs have no page naming this error.
The message
“unexpected status {status}: {body}”
That is the template in Codex's source. Codex fills in the HTTP status and the server's response body, so a 401 shows up as “unexpected status 401 Unauthorized” followed by a colon and the server's text, which is how users report it.
What it means
Codex builds this line from the HTTP status of a failed request and the body the server sent back, so “401 Unauthorized” is the server's answer and the text after the colon is the server's explanation. The user reports on the tracker show several different explanations behind the same first words: an “Incorrect API key provided” message (#48237), a bare {"detail":"Unauthorized"} (#26497), and “Missing scopes: api.responses.write” (#33664). All three are user reports, so read what follows the colon before deciding which one you have.
What you can do
- Check which sign-in Codex is using. The auth docs say to run
codex login statusto see the active authentication method. - Sign out and back in. The docs say
codex logoutclears stored credentials andcodex loginstarts the browser flow again. Codex's source has its own message for a login that can no longer be refreshed, “Your access token could not be refreshed because your refresh token has expired. Please log out and sign in again.”; if that is what you see, that is the instruction. - If many people are hit at once, wait. On 2026-09-25 a Codex team member (etraut-openai) answered a 401 report with “This is a widespread outage.” and later “Issue has been mitigated.” That statement was about that one incident. This site tracks the OpenAI status feed on /status/.
- For login problems the auth docs say direct
codex loginruns write a dedicatedcodex-login.logfile under your configured log directory.
On this site: install Codex CLI · check your Codex usage · did Codex reset today? · OpenAI status
Also searched as
People look this message up in several ways. These are search wordings, not OpenAI's text:
- cli unexpected status 401 Unauthorized
- VSCode Codex unexpected status 401 Unauthorized
Both are titles of user reports on the openai/codex tracker (issues #26497 and #9227), not OpenAI wording.
Sources
- openai/codex source: codex-rs/protocol/src/error.rs — fetched 2026-11-09
- Codex docs: Authentication — fetched 2026-11-09
- openai/codex source: codex-rs/login/src/auth/manager.rs (refresh-token message) — fetched 2026-11-09
- openai/codex issue #48237: user report with the Codex-team outage replies quoted above — fetched 2026-11-09
- openai/codex issue #26497 (user report) — fetched 2026-11-09
- openai/codex issue #33664 (user report) — fetched 2026-11-09
This site is not affiliated with OpenAI. Where a statement above comes from a user report or a reply on the openai/codex issue tracker rather than documentation, it says so.
Frequently asked questions
What does “unexpected status 401 Unauthorized” mean in Codex?
Codex's source formats any failed request as “unexpected status” followed by the HTTP status and the response body. So a 401 means the server answered with 401 Unauthorized, and the words after the colon are the server's own explanation, which differs between reports.
How do I fix “unexpected status 401 Unauthorized” in Codex?
The docs give the sign-in commands: codex login status shows the active method, codex logout clears stored credentials, and codex login signs in again through the browser. No docs page names this error, so these are the documented sign-in steps rather than a documented fix for it.
Is “unexpected status 401 Unauthorized” a Codex outage?
Sometimes. On 2026-09-25 a Codex team member called one such wave a widespread outage and later said it had been mitigated. The same words also appear in reports with an incorrect API key or missing scopes, so check the text after the colon and /status/.