Anthropic API authentication_error (HTTP 401): why it happens and how to fix it

If your Claude API call returned HTTP 401 with "type": "authentication_error", the API rejected your key before it even looked at your request. This is almost always one of six specific problems — and every one of them is fixable in under a minute once you know which one you have. This page walks through each cause, how to diagnose it, and the exact fix.

What the error actually looks like

Every Anthropic API error returns a structured JSON body. A 401 looks like this:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

The type field inside the error object is the authoritative signal. If you see authentication_error, the problem is the key itself. Anthropic's full error taxonomy for reference:

The 6 most common causes of a 401 — and how to fix each

1. Passing the literal placeholder string

The most common cause, especially when following tutorials: the code contains the literal string "YOUR_API_KEY" or "sk-ant-XXXXXXX" rather than a real key.

# Wrong — literal placeholder
client = anthropic.Anthropic(api_key="YOUR_API_KEY")

# Also wrong — hardcoded real key (security risk, and fragile)
client = anthropic.Anthropic(api_key="sk-ant-api03-...")

Fix: always load the key from an environment variable, not from a string literal in source code.

2. Wrong environment variable name

The Anthropic Python and TypeScript SDKs look for exactly ANTHROPIC_API_KEY. Common wrong names that cause a 401:

If you call anthropic.Anthropic() with no api_key argument, the SDK reads os.environ["ANTHROPIC_API_KEY"]. If that variable doesn't exist, you get a 401.

3. Key revoked or deleted in the console

Keys can be revoked by any admin in your workspace, or automatically invalidated if a security scan detects them in a public repo. Go to console.anthropic.com → API Keys and confirm the key status is Active. If it's been revoked, generate a new one — revoked keys cannot be re-activated.

4. Whitespace or newline embedded in the key string

When copying a key from a browser or terminal, it's easy to accidentally include a trailing newline, space, or tab. These characters are invisible in most editors and .env files, but the API sees a different string and rejects it. Fix:

import os
import anthropic

# Strip whitespace to be safe
api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
client = anthropic.Anthropic(api_key=api_key)

You can also run echo -n "$ANTHROPIC_API_KEY" | wc -c in your shell and compare the character count to the known key length (Anthropic keys are typically 108 characters including the sk-ant-api03- prefix). A mismatch means you have extra characters.

5. Using an OpenAI key with the Anthropic SDK (or vice versa)

OpenAI keys start with sk-proj- or sk-. Anthropic keys start with sk-ant-. If you have both providers in a project, it's easy to mix up which key is assigned to which variable. The Anthropic API will return a 401 immediately if it receives an OpenAI key — they are not interchangeable.

6. Key exists but has no permissions for the model requested

This is the boundary case between a 401 and a 403. If the key itself is valid but the workspace or key doesn't have access to the specific model string you passed (e.g., a model ID that doesn't exist or is in limited access), you may see a 403 permission_error rather than a 401. If you've already confirmed the key is correct and active but are still getting a key-related error, check the exact HTTP status: 401 = key invalid; 403 = key valid but access denied.

The correct pattern: environment variable, not hardcoded key

The right way to authenticate is to load the key from the environment and never put it in source code:

import anthropic
import os

# Correct: read from environment variable
client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Shorthand: if ANTHROPIC_API_KEY is set, the SDK finds it automatically
client = anthropic.Anthropic()

# Set the variable in your shell before running:
# export ANTHROPIC_API_KEY="sk-ant-api03-..."
# Or add it to a .env file (and add .env to .gitignore)

For local development, a .env file loaded with python-dotenv is the standard approach. In production (AWS Lambda, Railway, Fly.io, etc.), set it as a secret environment variable in the platform UI — never commit it to your repository.

401 vs. 403: know the difference before debugging

These two errors are often confused because both block your request:

• 401 authentication_error — the key cannot be verified at all. The API doesn't know who you are. Fix the key itself.
• 403 permission_error — the key is valid and the API knows who you are, but your account or key doesn't have access to the specific resource. Fix: check model access in your workspace settings, confirm you have the right tier for the model, or contact Anthropic support for access to limited-availability models.

A 401 is always a key problem. A 403 is always an access/permissions problem on an otherwise valid key.

FAQ

What does the error message "invalid x-api-key" mean specifically? It means the string you passed in the x-api-key header (or via the SDK) did not match any active API key in Anthropic's system. The most likely causes are: the key has been revoked, the key string has extra whitespace, or the variable name was wrong and the key was never read.

What is the correct environment variable name for the Anthropic API key? ANTHROPIC_API_KEY (all caps, with underscore). The Anthropic Python and TypeScript SDKs read this variable automatically when no api_key argument is passed to the client constructor.

What is the difference between a 401 authentication_error and a 403 permission_error from the Anthropic API? A 401 means the key itself is invalid and cannot be verified. A 403 means the key is valid but doesn't have access to the specific resource or model you requested. Fix a 401 by correcting the key; fix a 403 by checking model access and workspace settings.

Last updated May 28, 2026. Error codes and behavior verified against Anthropic's official API documentation. Anthropic may update their error taxonomy or key formats — confirm specifics in the current docs before relying on them in production.