Claude Code 报错怎么办?Invalid API key、401、Credit balance is too low、529、Unable to connect 对照排查(2026)
Claude Code 的报错大致分四类:凭据(Not logged in、Invalid API key、401)、余额与限额(Credit balance is too low、429)、服务端(500、529)、网络(Unable to connect to API)。先跑 /status 看清是哪个凭据在生效,再按对照表逐项处理;排查时只看变量名,别把密钥打到屏幕上。
1. 先跑 /status:看清是哪个凭据在生效
Claude Code 的报错信息都很短,但官方错误文档给了一个统一的起点:认证相关的问题,先在会话里跑 /status,它会列出当前生效的凭据;登录和 API key 同时存在时,/status 会标出没在用的那一个。看 /status 时重点看三处:有没有 API key 或 Auth token 一行、它来自哪个变量;有没有 Anthropic base URL 一行,这一行只有设置了网关地址才会出现;登录方式是不是你以为的那个账号。很多人遇到报错的第一反应是重装或者反复 /login,但如果生效的是环境变量里的 key,/login 替换不了它 —— 官方在 401 一节写得很清楚,已批准的 ANTHROPIC_API_KEY 生效时优先于登录。先看 /status,再决定往哪个方向核实。
/status
# 只列出 ANTHROPIC 开头的变量名,不打印值
env | grep -oE "^ANTHROPIC[A-Z_]*"2. 凭据优先级:为什么登录了还报 Invalid API key
按官方认证文档,同时存在多种凭据时,Claude Code 按固定顺序取用:云平台凭据(设置了 CLAUDE_CODE_USE_BEDROCK 这类变量时)→ ANTHROPIC_AUTH_TOKEN(以 Authorization: Bearer 头发送)→ ANTHROPIC_API_KEY(以 X-Api-Key 头发送)→ apiKeyHelper 脚本的输出 → CLAUDE_CODE_OAUTH_TOKEN → Anthropic profile 与联合身份凭据 → /login 的订阅登录。订阅登录排在最后。所以你明明已经 /login,只要 shell 里还留着一个旧的 ANTHROPIC_API_KEY,而且你在交互模式里批准过它(交互模式下第一次遇到会询问一次,选择会被记住;非交互的 -p 模式只要存在就会使用),请求就会带着那个 key 发出去:key 失效就是 Invalid API key,key 所在组织被停用就是 401。官方给的回退办法是 unset ANTHROPIC_API_KEY,再用 /status 确认生效的是订阅登录。还有一个隐蔽来源要排除:direnv、dotenv 类 shell 插件和 IDE 内置终端,可能从项目里的 .env 文件自动加载旧 key,你自己从没手动设置过。
unset ANTHROPIC_API_KEY
# 再打开 ~/.zshrc 或 ~/.bashrc,删掉 export ANTHROPIC_API_KEY 那一行,开一个新终端启动 claude
# Windows PowerShell
Remove-Item Env:ANTHROPIC_API_KEY3. 排查时别把密钥打到屏幕上
不少排查教程,包括官方错误文档里的一条建议,会让你运行 env | grep ANTHROPIC 查看环境变量。这条命令会把 key 的完整值打印到终端,而终端内容很容易被截图发进群里、被录屏,或者留在共享机器的滚动记录里。排查其实只需要知道两件事:哪些变量存在,以及它们是从哪里来的,不需要看到值。可以改用只输出变量名的写法;要确认某个变量有没有设置,用判断语句只回答「已设置 / 未设置」。如果怀疑 key 里混进了换行或空格,较新版本的 Claude Code 会在 Invalid API key 后面直接说明是第几个字符有问题,这种情况 API 根本没有收到这个 key;重新从 Console 复制一次、确认没有多余换行即可,同样不需要把 key 打出来。地址也可能包含敏感参数,只核对主机名,不要直接输出完整配置值。万一 key 已经出现在截图或聊天记录里,别犹豫,去 Console 撤销并重新生成。
env | grep -oE "^ANTHROPIC[A-Z_]*"
[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY 已设置" || echo "ANTHROPIC_API_KEY 未设置"
[ -n "$ANTHROPIC_AUTH_TOKEN" ] && echo "ANTHROPIC_AUTH_TOKEN 已设置" || echo "ANTHROPIC_AUTH_TOKEN 未设置"
[ -n "$ANTHROPIC_BASE_URL" ] && echo "ANTHROPIC_BASE_URL 已设置" || echo "ANTHROPIC_BASE_URL 未设置"4. Invalid API key 和 401 Invalid authentication credentials 不是一回事
两条报错看起来都像「key 不对」,官方给的含义并不一样。Invalid API key · Fix external API key:来自 ANTHROPIC_API_KEY 或 apiKeyHelper 的 key 被 API 拒绝,或者 Claude Code 在发送之前就发现它带有请求头放不下的字符。处理办法是核对拼写,去 Console 的密钥页确认这个 key 没被撤销;key 来自 apiKeyHelper 时,请管理员检查脚本配置和凭据来源,不要直接运行会把密钥打印到终端的脚本。API Error: 401 Invalid authentication credentials:API 认得凭据的格式,但拒绝了它背后的账号或组织,常见于凭据刚被撤销、组织被停用或移除了你的权限、账号本身被停用;官方明确说明,这不是 token 过期导致的。处理顺序:/status 显示 API key 在生效,就去 Console 轮换 key,或 unset 回到订阅;只显示登录,就 /login 一次;同一个登录反复 401,说明账号或组织已经不可用,要找组织管理员恢复权限。登录过期另有自己的提示,比如 Login expired、OAuth token revoked,按提示重新 /login 即可。
5. Credit balance is too low 与 429:余额和速率是两件事
Credit balance is too low 有两种来源。一是 Console 组织的预付余额真的用完了:去 Console 的账单页充值,官方也建议开启自动充值,并在 Console 给工作区设置支出上限,避免一个项目把整个组织的余额用光。二是你本来有 Pro、Max、Team 或 Enterprise 订阅,请求却被环境里已批准的 ANTHROPIC_API_KEY 接走了,用的是那个 key 所在组织的余额 —— /status 的 API key 一行就能看出来,unset 后重新启动 claude 即可。Request rejected (429) 是你的 API key,或 Bedrock、Google Cloud 项目撞到了配置的速率上限,和余额无关:先 /status 确认用的是预期的凭据,官方特别提到环境里混进一个低档位的 key 会让请求走它而不是订阅;再去提供方控制台查看当前限额;脚本里批量跑时少开并行子任务,或者用 /model 换一个更小的型号。订阅用户还会看到另一类提示,比如 You've hit your session limit、You've hit your monthly spend limit,那是订阅窗口或用量额度的上限,提示里会写明重置时间或调整入口,可以跑 /usage 查看各窗口什么时候重置。
6. 500 与 529:服务端的问题,不是你的账号
API Error: 500 表示 API 内部出现意外故障,官方说明它不是你的提示词、设置或账号导致的。API Error: Repeated 529 Overloaded errors 表示 API 暂时对所有用户都满负荷,Claude Code 显示这条之前已经自动重试过几次;官方明确 529 不是你的用量上限,也不计入你的额度。处理办法:去 status.claude.com 看有没有正在进行的事件;过几分钟再发,长提示不用重新粘贴,输入 try again 即可,原消息还在对话里;着急的话用 /model 换一个型号继续,因为容量是按型号分别计算的。报错末尾提示去哪里看服务状态,会随接入方式变化:走 Bedrock、Google Cloud 等会指向对应云的状态页,设置了自定义 ANTHROPIC_BASE_URL 时会写网关的地址。还有一种只在网关场景出现的情况:每个请求都以 500、401 或型号报错失败时,官方建议设置 ENABLE_TOOL_SEARCH=false 再试,排除网关拒收 Claude Code 默认发送的工具搜索字段。
7. Unable to connect to API:先测网络,再查残留的网关地址
这类报错说明 TCP 连接没建起来,括号里的代码指出大致方向:ConnectionRefused 是对方地址没有响应,ENOTFOUND 是域名解析不到,ECONNRESET 是连接被中途断开。官方给的第一步,是在启动 claude 的同一个 shell 里用 curl -I 测目标地址。如果 curl 通了、Claude Code 仍然连不上,问题通常不在网络本身,而在中间环节。一个很容易忽略的原因是 ANTHROPIC_BASE_URL 还指着一个已经停掉的本地网关或旧的中转地址:只要设置了它,Claude Code 就会把模型请求发往那里而不是官方 API,于是 curl 官方地址是通的,Claude Code 却报 Connection refused。除了 shell 环境,还要检查 Claude Code 设置文件里的 env 块;官方说明设置文件里设的值可能覆盖 shell 里 export 的值。Linux 和 WSL 上,再看一眼 /etc/resolv.conf 里的域名服务器是否可达。删掉残留配置后,从一个新终端启动 claude。
curl -I https://api.anthropic.com
# 走网关或中转时,测你自己配置的地址
curl -I "$ANTHROPIC_BASE_URL"
# 查设置文件里有没有残留的网关地址(只列匹配的文件名,不输出行内容)
grep -l "ANTHROPIC_BASE_URL" ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null8. 通过网关或 cocodot 接入:先验证,再长期保存
用 Anthropic 兼容的网关或中转跑 Claude Code 时,官方接入文档给的流程是先验证、再保存:先在 shell 里 export ANTHROPIC_BASE_URL 和凭据变量,用一条只要 1 个 token 的请求直接测网关。返回以 {"id":"msg_ 开头的 JSON,说明地址和凭据都可用;返回未知型号的错误,也说明认证已经通过;返回 401,说明凭据被拒。凭据放哪个变量要看网关的要求:网关说 bearer token 或 Authorization 头的,用 ANTHROPIC_AUTH_TOKEN;说 API key 或 x-api-key 的,用 ANTHROPIC_API_KEY。放错变量,凭据就进了网关不读的请求头,结果同样是 401。验证通过后从同一个 shell 启动 claude,用 /status 确认 Anthropic base URL 一行显示的是网关地址。官方特别提醒:不要把凭据写进项目的 .claude/settings.json,那个文件会随仓库提交,所有克隆的人都看得到。用 cocodot 接入时,按 /hub/claude-code 页设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个变量;新用户调用 API 须先完成实名认证,免费体验额度只可调部分低价型号。Claude / GPT / Gemini 各线挂牌价不超官网,逐型号以价格页实时标价为准。
MODEL="填网关支持的型号名"
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d "{\"model\": \"$MODEL\", \"max_tokens\": 1, \"messages\": [{\"role\": \"user\", \"content\": \".\"}]}"Claude Code 报错对照:症状 → 根因 → 先做什么
| 你看到的报错 | 根因 | 先做什么 |
|---|---|---|
| Not logged in · Please run /login | 这个会话里没有可用凭据 | 跑 /login;本打算用环境变量的,确认变量在启动 claude 的那个 shell 里已 export |
| Invalid API key · Fix external API key | 环境变量或 apiKeyHelper 给出的 key 被拒,或 key 里混进了换行等请求头放不下的字符 | 去 Console 确认 key 没被撤销;只列变量名找残留;不想用 key 就 unset 后 /login |
| API Error: 401 Invalid authentication credentials | 凭据刚被撤销,或账号 / 组织已停用;设了网关地址时是网关自己的报错 | 先 /status 看在用的是 key 还是登录,再按来源处理 |
| Credit balance is too low | Console 预付余额用完,或订阅请求被环境里的 key 接走 | /status 看 API key 一行;确实要用 key 就去 Console 充值 |
| API Error: Request rejected (429) | 这个 key 或项目撞到配置的速率上限 | 确认生效的是预期的凭据;减少并行子任务 |
| API Error: Repeated 529 Overloaded errors | 服务端暂时满负荷,不算你的用量 | 看 status.claude.com,稍后再试,或 /model 换型号 |
| Unable to connect to API(括号里带 ConnectionRefused、ENOTFOUND 等代码) | TCP 连接没建起来,或 ANTHROPIC_BASE_URL 指向已失效的地址 | 同一 shell 里 curl -I 目标地址;检查残留的 ANTHROPIC_BASE_URL |