Passion8Docs
Claude Code

错误参考

Claude Code 运行时错误、HTTP/API 状态、自动重试、用量限制、认证、网络、请求和命令行错误的处理方式。

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

接入 Passion8 时,同一个错误可能来自上游模型、Passion8 网关、本地网络或 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 context1M 上下文资格关闭 1M 或补足官方账号要求
Request rejected (429)限流等待、降并发、减少后台 agent
Credit balance is too low余额Passion8 后台充值或更换 Key
Not logged in官方登录/login 或改用 API/Passion8 环境变量
Invalid API key认证检查 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY
Unable to connect to API网络检查代理、DNS、防火墙、Base URL
SSL certificateTLS/证书配 NODE_EXTRA_CA_CERTS 或修复代理证书
Prompt is too long请求过大/compact、删大文件、拆任务
Request too large请求体过大缩短附件、图片、PDF 或工具结果
selected model模型不可用/model 选择 Passion8 可用模型
thinking budget exceeds output limitthinking 配置降 thinking token 或提高输出上限
--bg and --print conflictCLI 参数冲突二选一,后台任务不要同时 print

#自动重试

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

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

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

#服务端错误

#500

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

处理顺序:

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

#529

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

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

#响应中途断开

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

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

#用量和额度

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

#认证错误

Claude Code 有两类认证路径:

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

Passion8 推荐:

export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key"
claude -p "只回答 ok"

Claude Code 接 Passion8 的 Base URL 是 https://passion8.cc,不要带 /v1。/v1 是 OpenAI 兼容客户端常用路径。

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

#网络和证书

现象可能原因处理
Unable to connect to APIDNS、代理、防火墙、Base URLcurl -I https://passion8.cc,确认代理变量
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 或 thinkingkey 变化,通常 miss
/compact 后继续历史被摘要替换,后续前缀改变
修 MCP 或 Hooks工具 schema 或系统提示可能变化
重开干净配置适合排错,不能拿它判断正常缓存命中

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

#官方参考

上一页术语表下一页常见问题

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right