排错指南 · Claude Code

Claude Code 常见报错:一条一条对照着修

换到第三方 API 后,90% 的问题集中在五类:密钥、余额、模型名、限流、上游渠道。 先看对照表定位,再按小节处理。

先做一次最小验证。 用 curl 直接打一次 /v1/messages,能区分是「客户端配置问题」还是「账号/上游问题」。

对照表

报错 → 原因 → 解法速查
401 API_KEY_REQUIRED / invalid token   → 没带密钥或密钥不完整 → 重设 ANTHROPIC_AUTH_TOKEN
402 / 403 insufficient balance         → 余额不足             → 充值,1 元 = 1 美元额度
429                                    → 限流/并发超限         → 降并发,几秒后重试
404 model not found / not available    → 分组不支持该模型      → 换分组或换模型名
Model "xxx" isn't recognized           → 同上(客户端提示)    → /model 选择分组内模型
503 No available channel               → 上游临时无渠道        → 重试;持续则查渠道状态
连接超时 / PROTOCOL_ERROR               → 本地到 API 不通       → 换网络或换域名重试

401:密钥问题

常见三种情况:

  • ANTHROPIC_AUTH_TOKEN 没设置,或只设了旧的 ANTHROPIC_API_KEY;
  • 密钥复制不完整(少了 sk- 后面几位),或复制时带了空格;
  • 终端没重开,新环境变量没生效。
自检bash
# 确认两个变量都有值
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

# 若同时存在 API_KEY,删掉它
unset ANTHROPIC_API_KEY

402 / 403:余额不足

中转站按余额扣费,余额为 0 时上游会返回 insufficient balance。 充值后立即生效,不需要重新创建密钥。余额与每次调用的费用都能在控制台「用量」页看到。

429:限流或并发超限

Claude Code 会自动并行发多个请求。并发上限按账号设置,超过就返回 429。 处理方式:减少同时打开的任务、调小 --max-turns 或并行度,等几秒重试。 长期需要更高并发可联系客服。

Model isn't recognized / model not found

Claude Code 看到不认识的模型名时,会提示 Model "xxx" isn't recognized · context assumed to be 200k tokens, 随后报 There's an issue with the selected model。 这不是 Claude Code 坏了,是当前密钥所在分组里没有这个模型。

  1. 在控制台「API 密钥」看这个 Key 属于哪个分组;
  2. 在「价格」页确认该分组支持哪些模型;
  3. 用 /model 换成该分组里的模型,或换一个包含目标模型的分组新建 Key。
⚠️ 模型名必须完全一致(含版本后缀)。不要凭记忆输入,从价格页复制。

503:上游无可用渠道

No available channel for model ... under group ... 表示上游侧该模型暂时没有可用线路。 这类问题本地改配置无效,重试通常即可恢复;持续出现请看「渠道状态」页或联系客服。

连接超时

先排除网络:用 curl -m 10 https://api.hardysapi.com/health 测试。 若超时,换一个域名(https://hardysapi.com 与 https://api.hardysapi.com 等价)或换网络。 若返回正常但 Claude Code 仍失败,检查是否配置了本地代理,导致请求没有走对出口。

最小验证命令

Claude Messages 格式bash
curl https://api.hardysapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'

这条命令返回 content 就说明密钥、余额、模型都正常,问题在客户端配置; 如果它也报错,按上面的错误码继续排查。