Incorrect API key provided: the OpenAI 401 and every reason you get it

Incorrect API key provided: sk-***

The body is a 401 with the key redacted down to its first and last few characters, which is itself useful: those visible characters are enough to tell you which key was actually sent.

{
  "error": {
    "message": "Incorrect API key provided: sk-qVL45***************************************D1Vi. You can find your API key at https://platform.openai.com/account/api-keys.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

The docs list four 401 conditions and one 403, each with its own heading; a second 403 shape (code model_not_found on a project without model access) shows up in the wild but not in the docs. Matching your response to the right row is the whole diagnostic.

The four causes OpenAI lists, and the one it does not

Under the Incorrect API key provided heading the docs name four causes. They are worth quoting because each maps to a different check.

• "There is a typo or an extra space in your API key." This covers the whole family of copy-paste damage: a trailing newline from echo, a leading space from a terminal selection, a soft-wrapped key that picked up a line break in a config file.
• "You are using an API key that belongs to a different organization or project." The most common version of this is an org you forgot you had.
• "You are using an API key that has been deleted or deactivated." Deletion is immediate and irreversible.
• "An old, revoked API key might be cached locally." The docs suggest clearing your browser cache, which applies to dashboard sessions. For code, the cache is your environment.

The cause OpenAI does not document, because it is not their layer, is the one that produces the most confused bug reports.

Environment precedence

Nearly every SDK and framework resolves the key from OPENAI_API_KEY in the process environment, and nearly every .env loader refuses to overwrite a variable that is already set. So an export you added to ~/.zshrc six months ago silently wins over the correct key in the project file you are staring at, and the redacted prefix in the error message is your only clue that a different key was ever involved.

# what is in the environment right now?
echo "${OPENAI_API_KEY:0:8}...${OPENAI_API_KEY: -4}"

# where did it come from?
grep -rn "OPENAI_API_KEY" ~/.zshrc ~/.bashrc ~/.profile ~/.zshenv 2>/dev/null

# does it have trailing whitespace? a clean key prints exactly its length
printf %s "$OPENAI_API_KEY" | wc -c
echo "$OPENAI_API_KEY" | od -c | tail -2   # look for \n or \r at the end

# does the API agree it is valid?
curl -sS https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | jq '.error // "key is valid"'

Key types, projects, and the headers that go with them

Modern OpenAI keys are scoped to a project rather than to a user, and that scoping is where most of the remaining 401s live.

Two optional headers select which org and project a request bills to, and getting them wrong produces two different failures.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Organization: $ORGANIZATION_ID" \
  -H "OpenAI-Project: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-terra","input":"ping"}'

• Header disagrees with the key: 401. Sending OpenAI-Project for a project the key does not belong to has been reported as OpenAI-Project header should match project for API key. The fix is to drop the header, since a project key already identifies its project, or to send the matching one.
• Key valid, project lacks model access: 403. This is the one that misdirects people. The body reads Project \`proj_id\` does not have access to model \`gpt-5.2\` with code: model_not_found, so it reads like a model problem and is actually a project permissions problem. Check the project's allowed models before you go looking for the model ID.
• Admin keys are not inference keys. An sk-admin- key on /v1/responses gives you a permissions failure, and the message about permissions rather than about the key is the tell.

Rotation without an outage

A key is displayed once, at creation. There is no way to view it again, so rotation is always create-then-delete, never reveal-and-copy.

A decision table for the 401 in front of you

The single highest-yield check on that list is the first one. Print the redacted key from inside the running process, compare it to the one you intended, and about two thirds of these end there.

Questions people ask

Keep reading

Continue through Errors and fixes with This model's maximum context length is: fixing context_length_exceeded.