错误参考

这页用于定位已经进入 Claude Code 之后出现的错误。安装、PATH、登录和 OAuth 问题优先看 安装与登录排错。配置文件、Hooks、MCP 和记忆未生效看 配置调试与 .claude 目录。

接入 Gushen888 时,同一个错误可能来自上游模型、Gushen888 网关、本地网络或 Claude Code 配置。先看错误属于哪一类,再决定是重试、换模型、改配置还是联系支持。

快速定位

看到的错误	大类	优先动作
API Error: 500	服务端错误	等待后重试,检查上游或网关状态
Repeated 529 Overloaded errors	服务端容量	稍后重试或 /model 换模型
Request timed out	服务端或网络	拆小任务,必要时调 API_TIMEOUT_MS
Server error mid-response	流式响应中断	读已输出内容,回复 continue
You've hit your session limit	订阅或会话限制	等待窗口重置或换可用账号/provider
Usage credits required for 1M context	1M 上下文资格	关闭 1M 或补足官方账号要求
Request rejected (429)	限流	等待、降并发、减少后台 agent
Credit balance is too low	余额	Gushen888 后台充值或更换 Key
Not logged in	官方登录	/login 或改用 API/Gushen888 环境变量
Invalid API key	认证	检查 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY
Unable to connect to API	网络	检查代理、DNS、防火墙、Base URL
SSL certificate	TLS/证书	配 NODE_EXTRA_CA_CERTS 或修复代理证书
Prompt is too long	请求过大	/compact、删大文件、拆任务
Request too large	请求体过大	缩短附件、图片、PDF 或工具结果
selected model	模型不可用	/model 选择 Gushen888 可用模型
thinking budget exceeds output limit	thinking 配置	降 thinking token 或提高输出上限
--bg and --print conflict	CLI 参数冲突	二选一,后台任务不要同时 print

自动重试

Claude Code 会对临时失败自动重试。典型可重试场景包括 5xx、529、临时 429、请求超时和连接掉线。看到最终错误时,通常说明重试已经用完。

变量	作用	建议
CLAUDE_CODE_MAX_RETRIES	控制重试次数	CI 想快速失败可调低
CLAUDE_CODE_RETRY_WATCHDOG	无人值守时长时间重试容量错误	长任务、夜间任务谨慎开启
API_TIMEOUT_MS	单次请求超时	慢代理或超长输出可调高

不会盲目重试的场景:证书验证失败、已经有可见输出后的中途服务端错误。后者保留已输出内容,避免重复执行工具。

服务端错误

500

500 表示 provider 或网关内部失败。不是 prompt 写错,也不是权限规则问题。

处理顺序:

• 等 1 到 2 分钟后重试。
• 用 /model 切到另一个可用模型。
• 如果只在 Gushen888 下出现,检查 Gushen888 控制台和当前模型供应状态。
• 如果只在官方 Anthropic API 下出现,看官方状态页。

529

529 是容量拥塞,不等同于你的额度用尽。对长任务,不要开太多后台 agent 一起打同一个模型。

场景	建议
交互式开发	稍后重试或切 Sonnet/Opus 另一个可用模型
claude -p 脚本	加重试包装,失败时保留输入
/batch 或多 agent	降并发,把任务拆成队列
1 小时缓存任务	等待后重试,不要改动模型和 effort,避免缓存 key 变化

响应中途断开

如果已经看到部分回答,Claude Code 不会直接重跑整轮,因为这可能重复工具调用。常见做法是:

• 先读已经输出的部分。
• 回复 continue 或让它从最后一个小节继续。
• 如果中断发生在工具调用后,先确认文件和命令实际状态。

用量和额度

错误	含义	Gushen888 处理
session/weekly limit	官方 Claude 订阅限制	Gushen888 API Key 不解决官方订阅限制,改用 API 环境变量会走网关
1M context credits required	官方 1M 上下文资格不足	不要强开 1M,先用普通上下文和 /compact
temporary limiting requests	provider 临时限流	降并发,等待窗口
429	请求过密或额度窗口限制	降并发,避免并行子代理一起发大上下文
Credit balance is too low	当前 Key 或账户余额不足	到 Gushen888 后台检查余额、Key 状态和模型权限

认证错误

Claude Code 有两类认证路径:

路径	常见变量/命令	适合
官方登录	/login、OAuth、Claude subscription	官方 Claude Code on the web、Desktop、远程功能
API/网关	ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY	Gushen888、自定义 provider、CI

Gushen888 推荐:

export ANTHROPIC_BASE_URL="https://api.gushen888.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Gushen888 API Key"
claude -p "只回答 ok"

Claude Code 接 Gushen888 的 Base URL 是 https://api.gushen888.cloud,不要带 /v1。/v1 是 OpenAI 兼容客户端常用路径。

错误	检查
Not logged in	如果你想用官方订阅,运行 /login;如果想走 Gushen888,确认环境变量已经进入当前 shell
Could not resolve authentication method	不要同时混用不完整的 OAuth、API Key 和网关变量
Invalid API key	Key 是否复制完整,是否禁用,是否放到了正确变量
organization disabled	官方组织或企业策略问题,不是本地 settings 可修复
OAuth token expired	重新 /login,或删除旧登录后重登
Bedrock/Vertex credentials	检查云厂商凭据链和当前 profile

网络和证书

现象	可能原因	处理
Unable to connect to API	DNS、代理、防火墙、Base URL	curl -I https://api.gushen888.cloud,确认代理变量
TLS/SSL certificate	公司代理替换证书或 CA 缺失	配 NODE_EXTRA_CA_CERTS 或让 IT 下发根证书
cloud session host not allowed	云端 session 访问了禁止 host	改用本地 session 或放开允许列表
每次等很久才失败	代理握手或网络丢包	调 API_TIMEOUT_MS,同时修复网络根因

请求错误

上下文过长

Prompt is too long、Request too large 和 compaction 失败通常说明上下文或附件过大。

优先做:

• /context 查看占用。
• /compact 生成摘要。
• /clear 开新会话。
• 删掉不必要的大日志、截图、PDF、MCP 输出。
• 把大型代码库任务拆成目录级任务。

模型和 thinking

错误	处理
selected model issue	用 /model 选择当前 provider 确实有的模型
Opus not available	切 Sonnet 或使用支持 Opus 的账号/provider
model restricted by organization	需要组织管理员放开
thinking not supported	换支持 thinking 的模型或关闭 thinking
thinking budget exceeds output	降 MAX_THINKING_TOKENS 或提高输出预算
tool use block mismatch	通常是请求结构或网关透传问题,检查自定义网关是否改写 body

缓存影响

错误本身不会改变 5 分钟或 1 小时 TTL,但你的修复动作可能改变 cache key。

动作	缓存影响
原模型原 effort 直接重试	更可能命中已有前缀缓存
/model 换模型	新模型 cache key 不同,第一轮通常 miss
改 /effort 或 thinking	key 变化,通常 miss
/compact 后继续	历史被摘要替换,后续前缀改变
修 MCP 或 Hooks	工具 schema 或系统提示可能变化
重开干净配置	适合排错,不能拿它判断正常缓存命中

逐命令说明见 命令与缓存影响,底层规则见 Prompt 缓存。

官方参考

• Error reference
• Troubleshoot installation and login
• Troubleshooting
• Prompt caching