Claude API 401 Authentication Error: Troubleshooting Guide

Q: Should I use x-api-key or Authorization: Bearer for the Claude API?

The official Anthropic API expects the x-api-key header with a key that starts with sk-ant-. Gateways such as byesu authenticate with Authorization: Bearer sk-your-token on both the Anthropic-native /v1/messages endpoint and the OpenAI-compatible /v1/chat/completions endpoint. Sending the header that matches your key but not your endpoint is the single most common cause of a 401.

Quick answer

A 401 authentication_error means the server rejected your credentials before your prompt was processed — nothing is billed. Nine times out of ten it is a mangled key, the wrong auth header (x-api-key vs Authorization: Bearer), a wrong base_url, or a disabled key. Re-copy the key, match the header to your endpoint (Anthropic's official API uses x-api-key; gateways like byesu use Authorization: Bearer), then run the curl smoke test below.

Symptoms and What They Mean

The Anthropic-format error body looks like this:

json

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

The OpenAI-compatible format reports the same failure as "code": "invalid_api_key" with HTTP status 401. Either way it means "I could not verify who you are" — it is not a rate limit (429), a permission problem (403), or a wrong model name (404). Because the request is rejected at the front door, failed 401 calls consume no tokens and cost nothing — retry freely while debugging.

Cause Checklist

Work through these in order — sorted by how often they turn out to be the culprit.

#	Cause	Quick check
1	Key copied wrong — extra space, newline, or truncated	`echo -n "$ANTHROPIC_API_KEY" \| wc -c` and compare the length
2	Wrong auth header for the endpoint	Official Anthropic → `x-api-key`; byesu → `Authorization: Bearer`
3	Wrong `base_url` — key is valid but sent to a server that does not know it	Anthropic-native → no `/v1`; OpenAI-compatible → with `/v1`
4	Key deleted, disabled, or its quota exhausted	Check token status in the console
5	Stale environment — client still using an old key	Restart the terminal / editor after any config change

Fix 1: Verify the Key Format

Official Anthropic keys start with sk-ant-; byesu tokens start with sk-. A key that does not match the pattern your endpoint expects means credentials from two different services got mixed. Then rule out invisible characters — the classic failure is a trailing newline picked up while copying:

bash

# Length check: count must match the console exactly
echo -n "$ANTHROPIC_API_KEY" | wc -c

# Reveal hidden whitespace or newlines
printf '%q\n' "$ANTHROPIC_API_KEY"

When in doubt, go back to the console, copy the token again, and replace the entire string rather than editing it in place.

Fix 2: Use the Right Auth Header

This is the subtle one. The two ecosystems authenticate differently:

Official Anthropic API — x-api-key:

bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4-8","max_tokens":64,"messages":[{"role":"user","content":"Say hello in one word."}]}'

byesu (both endpoint formats) — Authorization: Bearer:

bash

curl https://byesu.com/v1/messages \
  -H "Authorization: Bearer sk-YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4.8","max_tokens":64,"messages":[{"role":"user","content":"Say hello in one word."}]}'

Send x-api-key where Authorization: Bearer is expected (or vice versa) and the server sees no credentials at all — a 401 even though the key itself is valid.

Fix 3: Check the base_url

A valid key sent to the wrong host is still a 401. The rule on byesu:

Anthropic-native (/v1/messages) → https://byesu.com — no /v1 suffix
OpenAI-compatible (/v1/chat/completions) → https://byesu.com/v1 — with /v1

The two most common mistakes: appending /v1 to ANTHROPIC_BASE_URL for Claude Code, and forgetting /v1 in the OpenAI SDK's base_url. If the curl smoke test above succeeds but your client fails, the problem is in the client's config, not the key.

Fix 4: Confirm the Key Is Still Alive

Keys fail silently over time: a token can be deleted, disabled, or hit its quota cap. Open Console → Tokens and confirm the token still exists, its status is normal, and its quota is not exhausted (a hard-capped token behaves like an expired one). If anything looks off, create a fresh token and swap it in.

Fix 5: Reload the Environment

Editing ~/.zshrc does not change already-running shells. After any key or URL change, close and reopen the terminal (or your editor — Cursor and VS Code cache environment variables at launch), then confirm:

bash

env | grep ANTHROPIC

On Windows, setx only affects new processes.

Client Configuration Cheat Sheet

Client	Where the key goes	Base URL	Notes
Claude Code	`ANTHROPIC_API_KEY` env var	`ANTHROPIC_BASE_URL=https://byesu.com` (no `/v1`)	If 401 persists, use `ANTHROPIC_AUTH_TOKEN` instead — it forces the `Authorization: Bearer` header
Cursor	Settings → Models → API key field	Override base URL: `https://byesu.com/v1`	Uses the OpenAI-compatible format; model id must match the console exactly
Cline	Provider settings → API key	`https://byesu.com/v1`	Pick the OpenAI Compatible provider for Bearer-token gateways; set the model id manually

Claude Code example, complete:

bash

# Add to ~/.zshrc or ~/.bashrc; reopen the terminal to apply
export ANTHROPIC_BASE_URL="https://byesu.com"
export ANTHROPIC_API_KEY="sk-YOUR_TOKEN"
export ANTHROPIC_MODEL="claude-opus-4.8"

Full walkthrough: Claude Code CLI Setup.

Calling Claude Through byesu

byesu is an AI API gateway with both OpenAI-compatible and Anthropic-native endpoints, so one sk- key covers Claude, GPT-5.6, Grok and Gemini — and one auth convention (Authorization: Bearer) works across every model and both formats. That uniformity removes a whole class of 401s, and the console shows each token's live status and quota, so a silently disabled key is diagnosed at a glance. Billing is pay-as-you-go with no subscription; top up with USDT, Alipay or WeChat Pay. If a key checks out everywhere and you still see 401, screenshot the request (key redacted) and contact support.

FAQ

What does "authentication_error: invalid x-api-key" mean?

It means the server rejected your credentials before your prompt was processed. The four usual causes are a mangled or truncated key, sending the wrong auth header for the endpoint (x-api-key vs Authorization: Bearer), a wrong base_url so the key lands on a server that does not know it, or a key that has been disabled, deleted or has exhausted its quota. The request never reaches the model and is not billed.

Should I use x-api-key or Authorization: Bearer for the Claude API?

The official Anthropic API expects the x-api-key header with a key that starts with sk-ant-. Gateways such as byesu authenticate with Authorization: Bearer sk-your-token on both the Anthropic-native /v1/messages endpoint and the OpenAI-compatible /v1/chat/completions endpoint. Sending the header that matches your key but not your endpoint is the single most common cause of a 401.

Why does Claude Code return 401 even though my key is correct?

Usually the environment variables were edited but never loaded — restart the terminal after changing ~/.zshrc or ~/.bashrc and confirm with env | grep ANTHROPIC. Another frequent cause is an extra /v1 in ANTHROPIC_BASE_URL: for byesu it must be https://byesu.com without /v1. If the 401 persists, set ANTHROPIC_AUTH_TOKEN instead of ANTHROPIC_API_KEY so Claude Code sends an Authorization: Bearer header.

Do requests that fail with 401 cost money?

No. A 401 is returned by the authentication layer before the request reaches any model, so no tokens are consumed and nothing is billed. You can retry a curl smoke test as many times as you need while debugging without spending anything.

How do I fix a 401 in Cursor or Cline?

Point both tools at the OpenAI-compatible endpoint: set the base URL to https://byesu.com/v1 (with /v1), paste the sk- token as the API key, and enter the model id exactly as shown in the console, for example claude-opus-4.8. In Cline pick the OpenAI Compatible provider rather than the Anthropic provider when using a Bearer-token gateway. A leading or trailing space pasted with the key is enough to trigger a 401.

Common Errors & Fixes — every error message, grouped by symptom
Claude Code CLI Setup — environment variables and one-click script
Quick Start (3 steps) — create a token · set the address · pick a model
Console Sign-up / Create Token — get an sk- token and check its live status

Claude API 401 Authentication Error: Troubleshooting Guide ​

Symptoms and What They Mean ​

Cause Checklist ​

Fix 1: Verify the Key Format ​

Fix 2: Use the Right Auth Header ​

Fix 3: Check the base_url ​

Fix 4: Confirm the Key Is Still Alive ​

Fix 5: Reload the Environment ​

Client Configuration Cheat Sheet ​

Calling Claude Through byesu ​

FAQ ​

What does "authentication_error: invalid x-api-key" mean? ​

Should I use x-api-key or Authorization: Bearer for the Claude API? ​

Why does Claude Code return 401 even though my key is correct? ​

Do requests that fail with 401 cost money? ​

How do I fix a 401 in Cursor or Cline? ​

Related Links ​

Claude API 401 Authentication Error: Troubleshooting Guide

Symptoms and What They Mean

Cause Checklist

Fix 1: Verify the Key Format

Fix 2: Use the Right Auth Header

Fix 3: Check the base_url

Fix 4: Confirm the Key Is Still Alive

Fix 5: Reload the Environment

Client Configuration Cheat Sheet

Calling Claude Through byesu

FAQ

What does "authentication_error: invalid x-api-key" mean?

Should I use x-api-key or Authorization: Bearer for the Claude API?

Why does Claude Code return 401 even though my key is correct?

Do requests that fail with 401 cost money?

How do I fix a 401 in Cursor or Cline?

Related Links