Claude Code 401 with a custom base URL: Invalid API key and AUTH_TOKEN, checked in order
As of November 20, 2026, a 401 after you point Claude Code at a custom API address is one of four things: the key and the endpoint belong to different services, ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are swapped, an old value is still sitting in the settings file env block, or the address has an extra /v1. Run /status first and read the Anthropic base URL and Auth token lines, then keep exactly one credential variable matching them.
Updated 2026-11-20
One key for Claude, GPT and leading Chinese models, billed per token, up and running in minutes.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
Four values to know first
The credential was rejected, not the network
Anthropic's API error reference defines 401 as authentication_error: the key itself is malformed, revoked, or expired. When the address points at a gateway, the text after 401 was written by that gateway, not by Anthropic.
ANTHROPIC_API_KEY travels in this header
The authentication reference says it is sent as the X-Api-Key header for direct Anthropic API access. When you also have a subscription login, an approved API key takes precedence over it, which is why a logged-in session can still fail on credentials.
ANTHROPIC_AUTH_TOKEN travels in this header
Its value is prefixed with Bearer and sent as the Authorization header, meant for gateways or proxies that authenticate with bearer tokens. The official advice: if nobody told you which one to use, start with this.
See the address and credential in effect
The gateway guide shows the Anthropic base URL line only when a gateway address is set. An Auth token or API key line means a gateway credential is active; a Login method line means your login is.
What a 401 on a custom address actually is
A 401 on a custom API address is rarely a network problem: the credential attached to the request is not accepted on the other side. The official errors page explains Invalid API key as the ANTHROPIC_API_KEY variable or an apiKeyHelper script returning a key the API rejected, or Claude Code blocking that key before it was sent.
The other message, API Error: 401 Invalid authentication credentials, is more specific: the API recognized the format of the credential but rejected the account or organization behind it, so an expired token is not the cause. There is a third case: when the address points at a gateway, the text after 401 is the gateway's own error and /login cannot change it, because the gateway wants a different credential. All three start the same way: run /status and see which address and which credential are in effect.
Two changes relevant to this 401, as of November 20, 2026
1. One more source of 401 sits on the gateway side: the official errors page says that if every request fails with a 401 once your gateway has the credential it expects, check whether the gateway accepts tool search fields; before v2.1.304, tool search was off behind a gateway unless you turned it on with ENABLE_TOOL_SEARCH. 2. apiKeyHelper failures look different now: when the script returns no key, the request reaches the API with a placeholder credential and is rejected with 401, and before v2.1.208 Claude Code spent the full retry budget resending that request with the placeholder credential and then reported a generic 401 authentication error instead of the script failure; from v2.1.208 on, a script that errors, times out or prints nothing surfaces as Your apiKeyHelper script is failing within three attempts.
Three dates: which variable goes where, the settings-file way, and the gateway-side 401
Common experience in community troubleshooting discussions: a custom endpoint takes ANTHROPIC_AUTH_TOKEN, a direct connection to api.anthropic.com takes ANTHROPIC_API_KEY. Under that split, a gateway address paired with an Anthropic key, or a direct address paired with a gateway key, cannot match request headers, so the far side can only answer 401.
Common experience in community troubleshooting discussions: put the address and the gateway key into the env block of ~/.claude/settings.json instead of exporting them in the terminal only. Two rules repeat: fill the address up to the host and leave /v1 off, and when the same variable exists twice, the settings file wins.
When the gateway already has the right credential and every request still returns 401, check whether the gateway accepts tool search fields; before v2.1.304 that feature was off behind a gateway and had to be enabled with ENABLE_TOOL_SEARCH. The same docs note the Anthropic base URL line in /status appears only when a gateway address is set.
What the official docs confirm vs community claims and unpublished details
Confirmed by Claude Code's errors, authentication, environment variable, gateway and settings docs, plus Anthropic's API error reference
1. Both messages: Invalid API key · Fix external API key means ANTHROPIC_API_KEY or an apiKeyHelper script gave a key the API rejected, or Claude Code blocked it before sending; API Error: 401 Invalid authentication credentials means the format was recognised but the account or organization was rejected, so an expired token is not the cause. 2.
Headers: the AUTH_TOKEN value is prefixed with Bearer and sent as Authorization; API_KEY is sent as X-Api-Key. 3. Precedence: AUTH_TOKEN ranks above API_KEY, and a login ranks below both; in interactive mode an API key needs your approval once, while in -p mode the key is used whenever present. 4. Gateway case: when the address points at a gateway, the text after 401 is the gateway's message and /login does not change it; the credential belongs in AUTH_TOKEN, API_KEY or apiKeyHelper, whichever the gateway wants. 5.
Settings files: the env block applies everywhere Claude Code runs, user-level ~/.claude/settings.json covers all your projects, project-local .claude/settings.local.json covers one project, and a project's .claude/settings.json is committed, so no credentials there. 6. Neighbours: 403 is insufficient permission, 429 is a rate or spend limit, 529 is an overloaded API, and none of them is a credential problem.
Community claims and what the official docs do not say
1. Adding /v1 to the address is safer: community discussions say to leave /v1 off the end of the address, because /v1/messages is appended for you; the official verification request is written as $ANTHROPIC_BASE_URL/v1/messages, which shows /v1 is not part of the variable. On QCode the value is https://api.qcode.cc/api, and an extra /v1 on the end still produces a duplicated /v1/v1/messages. 2.
An export in the terminal is always in effect: the official docs warn that direnv, dotenv shell plugins and IDE terminals can load a stale key from a project .env file, and community posts report that the settings file wins when both set the same variable, so read /status before editing the shell. 3.
A fresh /login replaces an API key: it does not. The docs say an approved API key takes precedence over your login and /login does not replace it; unset it or rotate the key.
Two routes: API_KEY straight to Anthropic vs AUTH_TOKEN through a gateway
ANTHROPIC_API_KEY: a Console key for direct Anthropic API access
It is sent as the X-Api-Key header and comes from the Claude Console. In interactive mode you approve it once and the choice is remembered; in -p mode it is used whenever present. It outranks your subscription login, which is why a still-active plan can keep returning 401: rotate the key in the Console, or unset it and fall back to the subscription.
ANTHROPIC_AUTH_TOKEN: the bearer credential a gateway expects
Its value is prefixed with Bearer and sent as Authorization, for gateways that authenticate with bearer tokens. On QCode the address is https://api.qcode.cc/api with no /v1, and the credential is the key that starts with cr_; unset ANTHROPIC_API_KEY so two credentials never coexist. Official advice: when a gateway does not say which kind it wants, start with AUTH_TOKEN and confirm with a verification request.
Six steps: from the exact error line to a restarted, verified client
1. Read the exact line and sort it into one of three: Invalid API key · Fix external API key means the key was rejected or blocked before sending; API Error: 401 Invalid authentication credentials means the format was fine and the account or organization was rejected; when the address points at a gateway, the text after 401 belongs to the gateway, so change the credential it wants instead of running /login. 2.
Run /status: check whether the Anthropic base URL line is there and which address it names, then read the Auth token or API key line to see which credential is in effect. 3. Open ~/.claude/settings.json and look for a stale ANTHROPIC_BASE_URL or old key in the env block; when the same variable is also set in the settings file, the value you edit in the terminal may not take effect.
Never put credentials in a project .claude/settings.json, which gets committed. 4. Keep one credential variable: for a gateway set ANTHROPIC_AUTH_TOKEN and run unset ANTHROPIC_API_KEY; for direct Anthropic access do the reverse, keep ANTHROPIC_API_KEY and clear AUTH_TOKEN. 5. Check the address: QCode's Claude Code address is https://api.qcode.cc/api with no /v1, while Codex uses https://api.qcode.cc/openai; do not mix the two. 6.
Restart claude and send one minimal request with curl: POST $ANTHROPIC_BASE_URL/v1/messages with Authorization: Bearer $ANTHROPIC_AUTH_TOKEN and anthropic-version: 2023-06-01. A 401 means switch to the other variable and retry; a JSON body means both address and credential are right.
The QCode side: one address, one variable
QCode is an independent API access service with no affiliation to Anthropic, OpenAI or other vendors. Claude models go only through the Anthropic Messages endpoint: set ANTHROPIC_BASE_URL to https://api.qcode.cc/api with no /v1, set ANTHROPIC_AUTH_TOKEN to the key that starts with cr_, and unset ANTHROPIC_API_KEY so two credentials never coexist.
Put both lines in the env block of ~/.claude/settings.json, restart claude, then check the Anthropic base URL and Auth token lines in /status. Codex uses a different address, https://api.qcode.cc/openai, so do not mix it with Claude Code. Billing is per token; current rates for each model are on /models.
Not ready for a monthly plan? Pay-as-you-go Packs start at $4 for a one-time quota you use within 7 days; if you already have a Personal Plan, add a booster pack when you need more quota.
Common questions
I exported ANTHROPIC_AUTH_TOKEN in my terminal and Claude Code still returns 401. Why?
Run /status first and read which credential the Auth token or API key line names and which address the Anthropic base URL line shows; that is the official way to see the credential source in effect. Three usual causes. One, a stale value in the settings file: anything written to the env block of ~/.claude/settings.json applies everywhere Claude Code runs and is not necessarily overridden by the new value in your terminal. Two, a key loaded from elsewhere: the docs warn that direnv, dotenv shell plugins and IDE terminals can load a key you never set explicitly from a project .env file, so run env | grep ANTHROPIC in the same shell. Three, a key from a different service than the endpoint: a custom endpoint paired with an Anthropic key, or a direct address paired with a gateway key.
What is the difference between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY?
The header and the use case. The AUTH_TOKEN value is prefixed with Bearer and sent as Authorization, for gateways or proxies that authenticate with bearer tokens. ANTHROPIC_API_KEY is sent as X-Api-Key and is meant for a Claude Console key on direct Anthropic API access. The official precedence list puts AUTH_TOKEN ahead of API_KEY, so with both present AUTH_TOKEN is used: behind a gateway keep it and unset the other, and for direct access do the reverse. When you do not know which one a gateway wants, the docs recommend starting with AUTH_TOKEN and confirming with a verification request.
Should ANTHROPIC_BASE_URL include /v1?
No. Do not add /v1 to the end of the address; /v1/messages is appended by Claude Code itself, and the official verification request is written as $ANTHROPIC_BASE_URL/v1/messages, which shows /v1 is not part of the value. An extra segment at the end produces /v1/v1/messages, the gateway cannot route that path, and the reply often looks like a credential problem. On QCode the value is https://api.qcode.cc/api, where /api is part of the address itself and not a duplicated /v1. The same rule does not hold for every client: OpenAI-compatible SDKs and Codex use addresses with /openai or /openai/v1.
What is the difference between 401 and 403?
401 is about the credential itself: the API reference defines it as authentication_error, meaning the key is malformed, revoked or expired. 403 is permission_error: the key is valid but has no permission for the requested resource, so check the organization and workspace access settings in the Console. One exception is worth remembering: if the 401 text begins with CORS requests are not allowed for this Organization, the key is not the problem, because the request carried an Origin header from a browser, and it has to be sent from your own back end instead; changing the key does nothing.
Are 429 and 529 key problems?
No. Neither number is about credentials and a new key will not fix them. 429 is rate_limit_error: the organization hit a rate limit, the monthly spend cap of its usage tier, or a spend limit on the Claude Code workspace; such a 429 can keep failing until access resumes and may arrive without a retry-after header. 529 is overloaded_error: the API is temporarily overloaded, which the docs say can happen when traffic is high across all users. The official SDK retries these transient failures automatically, twice by default, honouring retry-after.
What do I do when apiKeyHelper fails or requests keep returning 401?
Run the script by itself first and confirm it prints a valid key to stdout, which is the first official triage step. When the script returns no key, the request reaches the API with a placeholder credential and is rejected with 401: before v2.1.208, Claude Code spent the full retry budget resending that request with the placeholder credential and then reported a generic 401 authentication error instead of the script failure, and from v2.1.208 on, a script that errors, times out or prints nothing surfaces as Your apiKeyHelper script is failing within three attempts. When it takes longer than 10 seconds to return a key, a warning notice with the elapsed time appears in the prompt bar. If the script is healthy and you still get 401, check in /status whether its output is the credential in effect, because AUTH_TOKEN and API_KEY rank above apiKeyHelper and a leftover variable means the script's key is never used. Note that Claude Desktop and cloud sessions do not call apiKeyHelper and do not read these environment variables.
Sources
Claude Code error reference code.claude.com/docs/en/errors (checked 2026-11-20); authentication and precedence code.claude.com/docs/en/authentication (checked 2026-11-20); environment variables code.claude.com/docs/en/env-vars (checked 2026-11-20); LLM gateway connection code.claude.com/docs/en/llm-gateway-connect (checked 2026-11-20); settings files code.claude.com/docs/en/settings (checked 2026-11-20); Anthropic API errors platform.claude.com/docs/en/api/errors (checked 2026-11-20); community claims come from public discussion posts and are labelled as such in the body. All checked on 2026-11-20.
Line up the address and the credential, then verify with /status and one request
Create an account for a cr_ key, set ANTHROPIC_BASE_URL=https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN in Claude Code, and call models billed per token, with rates on /models.
Related reading
Pay-as-you-go Packs: no monthly plan, valid 7 days
Buy a one-time quota valid for 7 days or add a booster pack to a Personal Plan; per-model rates are on /models.
ANTHROPIC_BASE_URL in Claude Code: Set a Custom API Endpoint
Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, as env vars or in settings.json, to point Claude Code at a custom endpoint. Also 1M context, /autocompact.
Claude Code Subagent & Default Model Env Vars Setup Guide (2026-11)
As of 2026-11-22: precedence, alias pinning, v2.1.330 fixes, and ~/.claude/settings.json gateway templates for ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, and CLAUDE_CODE_SUBAGENT_MODEL.
Crypto payment guide
Nine coins, 56 networks, zero platform fee for AI coding API credits.
Anthropic's Claude Code documentation and API error reference were checked on 2026-11-20 and are authoritative at code.claude.com and platform.claude.com. QCode.cc is an independent API access service with no affiliation to and no endorsement from Anthropic or OpenAI, and it cannot change how a vendor judges your account or key. QCode model availability and live rates follow qcode.cc/models.