“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

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:

Both are titles of user reports on the openai/codex tracker (issues #26497 and #9227), not OpenAI wording.

Sources

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/.