Claude Code 接 API 常见报错：Invalid API key、Not logged in、403 怎么解决

在 claude 里输入 /status，和 API 有关的是这三行：

• Anthropic base URL：请求发往的地址。没有这一行，说明没设 ANTHROPIC_BASE_URL，请求直接发给了 Anthropic 官方。
• Auth token：ANTHROPIC_AUTH_TOKEN 从哪里来。
• API key：ANTHROPIC_API_KEY 从哪里来。

某一行后面标着 not in use，说明这个值存在，但没有被用上。settings.json 里 env 写的值会盖过终端里设的同名变量，改了终端变量却不起作用，多半是这个原因，详见《ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别》。

服务端拒绝了 ANTHROPIC_API_KEY 里的 Key，返回 401。常见原因：

• Key 复制时多了或少了字符，或者前后带了空格、引号。
• Key 已经停用或删除。
• Key 和地址不是同一家的。
• 服务商要的是 Authorization 请求头，而 ANTHROPIC_API_KEY 发的是 x-api-key，这时改用 ANTHROPIC_AUTH_TOKEN。

改完新开一个终端再试。Key 写在 settings.json 里的，改 settings.json。

这句提示有两种情况。一是 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 都没设，Claude Code 以为你要用 claude.ai 账号登录。二是设了 ANTHROPIC_AUTH_TOKEN，但服务端返回了 401：Claude Code 2.1.312 这时显示的也是这一句，而不是 Key 无效。

用第三方地址时不要照提示去 /login。先用 /status 看 Auth token 那一行在不在，在的话按上一节核对 Key 本身。

完整的报错一般以 Failed to authenticate. API Error: 403 开头，后面是服务端返回的内容，比如 Request not allowed。最常见的原因是请求直接发给了 Anthropic 官方，而所在地区不在 Anthropic 的服务范围内。Anthropic 的排障文档写着：报错里出现 App unavailable in region，就是 Claude Code 在你所在的国家不能用。

• 本来打算走第三方地址的，用 /status 看有没有 Anthropic base URL 那一行。没有的话，ANTHROPIC_BASE_URL 没生效，请求还是发给了官方。
• 浏览器能打开 claude.ai，终端里的 claude 却报 403：终端不一定走系统代理，要在终端里单独设 HTTPS_PROXY。
• 用 Claude 订阅登录的，Anthropic 建议先到 claude.ai/settings 确认订阅还有效；用 Console 的 API Key，要确认账号有 Claude Code 或 Developer 角色。
• 第三方服务回 403 的原因各家不同。看 403 后面那段文字，按服务商的说明处理。

完整的提示是 There's an issue with the selected model (模型名). It may not exist or you may not have access to it. 服务端返回 404 时，Claude Code 显示的都是这一句，所以问题不一定出在模型上。

• ANTHROPIC_BASE_URL 末尾多写了 /v1。Claude Code 会自己在地址后面加 /v1/messages，写成 https://example.com/v1，请求就发到了 /v1/v1/messages，服务端回 404。地址写到域名和端口为止，除非服务商明确要求带路径。
• 服务商没有这个模型，或者你的 Key 不能用它。Claude Code 2.1.312 用 API Key 时默认用 claude-opus-5-5。用 /model 换一个，或者启动时加 --model claude-sonnet-5-5。

API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

Claude Code 连不上这个地址：域名或端口写错了，服务没开，或者被防火墙、代理挡住了。用下面的 curl 单独测一次。curl 也连不上，问题在网络或地址，与 Claude Code 无关。

Claude Code 遇到请求失败会自动重试，401 也会重试，所以 Key 写错时要等一阵才看到报错。排查时可以关掉重试，报错马上就出来：

CLAUDE_CODE_MAX_RETRIES=0 claude -p "hi"

排查完去掉这个变量。正常使用时，重试能扛过偶尔的网络抖动。

绕开 Claude Code，直接发一条最小的请求。服务商要 x-api-key 请求头的：

curl https://你的服务地址/v1/messages \
  -H "x-api-key: 你的key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'

服务商要 Authorization 请求头的，把第二行换成 -H "Authorization: Bearer 你的key"。

• 返回一段带 content 的 JSON：地址和 Key 都没问题，回去检查 Claude Code 的设置。
• 401：Key 不对，或者请求头用错了。
• 404：地址的路径不对，看看是不是多了或少了一段。
• 连不上：网络或地址的问题。

完整的设置方法见《用 API Key 接入 Claude Code》。两个 Key 变量用哪一个，见《ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别》。