换到第三方 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 不通 → 换网络或换域名重试
常见三种情况:
ANTHROPIC_AUTH_TOKEN 没设置,或只设了旧的 ANTHROPIC_API_KEY;sk- 后面几位),或复制时带了空格;# 确认两个变量都有值 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN # 若同时存在 API_KEY,删掉它 unset ANTHROPIC_API_KEY
中转站按余额扣费,余额为 0 时上游会返回 insufficient balance。
充值后立即生效,不需要重新创建密钥。余额与每次调用的费用都能在控制台「用量」页看到。
Claude Code 会自动并行发多个请求。并发上限按账号设置,超过就返回 429。
处理方式:减少同时打开的任务、调小 --max-turns 或并行度,等几秒重试。
长期需要更高并发可联系客服。
Claude Code 看到不认识的模型名时,会提示
Model "xxx" isn't recognized · context assumed to be 200k tokens,
随后报 There's an issue with the selected model。
这不是 Claude Code 坏了,是当前密钥所在分组里没有这个模型。
/model 换成该分组里的模型,或换一个包含目标模型的分组新建 Key。
No available channel for model ... under group ... 表示上游侧该模型暂时没有可用线路。
这类问题本地改配置无效,重试通常即可恢复;持续出现请看「渠道状态」页或联系客服。
先排除网络:用 curl -m 10 https://api.hardysapi.com/health 测试。
若超时,换一个域名(https://hardysapi.com 与 https://api.hardysapi.com 等价)或换网络。
若返回正常但 Claude Code 仍失败,检查是否配置了本地代理,导致请求没有走对出口。
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 就说明密钥、余额、模型都正常,问题在客户端配置;
如果它也报错,按上面的错误码继续排查。