简体中文繁體中文English
登录 免费开始
Troubleshooting · 排查手册

Claude Code 报错排查手册

按错误码对号入座，每条都给一句话原因和一步操作。大部分接入问题出在环境变量没生效、地址写错、并发到顶这三件事上——先看速查表，多半三十秒就能解决。

速查表

你看到的多半是先做这一步
401 · Invalid tokenKey 没生效或复制不全完整排查 →
403Key 被禁用或权限不足完整排查 →
429 · rate limit并发到顶，不是没钱完整排查 →
Connection error地址写错或网络不通完整排查 →
SSL / certificate代理或防火墙在中间拆包完整排查 →
model not found模型名带错版本或后缀完整排查 →
context length exceeded会话攒太长完整排查 →
流式回答中途断网络或代理超时掐断看代理超时设置
529 · overloaded 过载上游模型过载，非你的配置问题稍后重试或换模型
x-bb-api-key 等第三方报错由其他服务返回，不是 9Coding 的报错判断报错来源 →

连接与鉴权

401 · Invalid token#

症状
请求直接被拒，响应体形如 {"error":{"code":"","message":"Invalid token (request id: 2026...)","type":"new_api_error"}}。
原因
服务端没认出这把 Key。九成不是 Key 本身的问题，而是环境变量没生效或复制时被截断。
解决

先确认变量真的被读到了：

terminal
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

输出为空 → 变量没写进当前 shell 的配置文件，或者写完没重开终端。Claude Code 只在启动时读一次环境变量，改完必须重开终端（或 source ~/.zshrc）。

有输出但仍报 401 → 检查 Key 是否以 sk-9c- 开头、尾部有没有漏字符。从控制台重新复制一次最稳妥。

403 · Forbidden#

症状
Key 被识别了，但这次调用不被允许。
原因
Key 已被禁用、已删除，或该 Key 被限制了可用范围。
解决
到控制台的 Key 管理页确认这把 Key 还在、状态正常。删掉重建一把是最快的验证方式——新 Key 立刻生效，不需要等。

Connection error · 连不上#

症状
请求还没到服务端就失败，报连接错误、ECONNREFUSED 或超时。
原因
要么地址写错，要么网络出不去。先把 Claude Code 排除在外，用 curl 直接打端点，一步就能分开这两种情况。
解决
terminal
curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

curl 能通（返回模型列表或 JSON 错误）→ 网络没问题，是客户端配置。检查 ANTHROPIC_BASE_URL 有没有拼错、结尾多了 / 或多写了 /v1。正确值就是 https://api.9coding.com，路径由客户端自己拼。

curl 也不通 → 网络或代理问题。检查系统代理是否只对浏览器生效、公司网络有没有拦截，终端里试试 curl -v 看卡在哪一步。

SSL / certificate 错误#

症状
报证书校验失败、unable to get local issuer certificate、握手超时。
原因
中间有代理或安全软件在拆 TLS，而它的根证书没被系统信任。
解决
把代理软件的根证书装进系统钥匙串，或临时关掉代理验证是不是它。不要用跳过证书校验的方式绕过——那等于把流量明文暴露给中间人。

限流与超时

429 · rate limit#

症状
请求被限流，提示 rate limit 或 too many requests。
原因
这是并发到顶，不是余额不够。两者的提示完全不同，余额问题会明确说余额不足。
解决

等几秒重试，通常自行恢复。频繁触发说明并行开得太猛：把同时跑的任务数降下来。

批量脚本一定要加指数退避——失败后等 1 秒、2 秒、4 秒逐次拉长，而不是原地猛重试。密集重试只会让限流持续更久。

529 · overloaded 模型过载#

症状
返回 529、提示 overloaded 或模型过载。搜「claude 529 怎么解决」的多半就是这个。
原因
上游模型本身在高负载，跟你的配置无关。热门模型在高峰时段偶发。
解决
稍等重试；赶时间就先换一个同级模型继续干活。在 Claude Code 里用 /model 切换，会话不会丢。
深入
如果它是断在回答中间、一次都没重试，那是另一条到达路径，标准重试机制管不到它 —— 见 529 overloaded 详解。

流式回答中途断掉#

症状
回答输出到一半停住，没有报错，或提示连接被重置。
原因
流式响应是一条长连接，中间任何一环的空闲超时都会掐断它——常见于公司代理和部分 VPN。
解决
把代理的读超时调大（长回答很容易超过 60 秒），或临时绕过代理验证。判断方法：同样的问题让它输出短一点，如果短回答正常、长回答必断，基本可以确定是超时掐断。

模型与参数

model not found · 模型名不对#

症状
提示模型不存在或不可用。
原因
手写模型名带错了版本号或多余后缀。模型 id 对大小写和短横线敏感，差一个字符就找不到。
解决

直接问服务端当前有哪些，照抄返回里的 id：

terminal
curl -s https://api.9coding.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

在 Claude Code 里用 /model 命令切换，从列表里选，比手输可靠。

context length exceeded · 上下文超限#

症状
提示上下文超出限制、token 数超标。
原因
会话累积的内容超过了模型的上下文窗口。长会话或一次性读入大文件时最常见。
解决

/clear 开新会话，或 /compact 压缩历史后继续。

长期办法是别把整个仓库一次性塞进去：让它按需读文件，比预先灌满上下文更省也更准。

以上都不是？按这个顺序查

遇到没见过的错误，不要从猜开始。这个顺序能在几分钟内把范围缩到一处：

  1. 看环境变量：echo $ANTHROPIC_BASE_URL $ANTHROPIC_AUTH_TOKEN。空的就是没生效，重开终端。
  2. 绕过客户端：用上面的 curl 直接打端点。能通就说明是客户端配置，不通就是网络。
  3. 换个模型：单个模型出问题和整条通道出问题，处理方式完全不同。
  4. 最小复现：新开一个空会话、问一句最简单的话。复杂会话里的报错往往和上下文有关，而不是接入本身。
  5. 还是不行就提交给我们——带上下面这些信息。
提交问题时请带上这四样：① 完整错误文本，尤其是里面的 request id（形如 request id: 2026...，能直接定位到那一次调用）；② 发生时间；③ 用的模型名；④ 上面第 2 步 curl 的结果。有这四样通常一次就能定位，只说「调不通」谁也查不了。

相关

免费开始 看接入教程