Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

错误参考

Claude Code 运行时错误的分类与排查思路：自动重试规则与调优变量、服务器错误、用量限制、认证、网络与请求错误等章节索引。具体消息的完整处理见官方原文。

本页整理 Claude Code 显示的运行时错误的分类，以及官方的自动重试规则；官方原文按具体错误消息逐条给出含义和处理办法（篇幅很大），遇到具体消息时请按下面的章节到原文查找。安装错误（如 command not found、安装时的 TLS 失败）见安装与登录排障。除 Wrapper 和 IDE 错误（由启动它的程序打印）外，这些错误和恢复命令适用于 CLI、桌面应用和云端会话，因为三者包装的是同一个 Claude Code CLI。Claude Code 调用 Claude API 获取模型回复，所以多数运行时错误对应底层的 API 错误码。

错误分类

官方原文按具体错误消息逐条给出含义和处理办法。这里按类别拆成几页，每条错误一个小节，写明「含义」和「怎么办」：

  • 服务器错误与用量限制：API Error: 500、Repeated 529 Overloaded errors、Request timed out、No response from API、响应可能不完整、auto mode 无法判断安全性；session/weekly/Opus/Sonnet 用量限制、Credit balance is too low、Request rejected (429) 等
  • 认证错误：Not logged in、Invalid API key、apiKeyHelper 失败、组织禁用 API Key 或订阅访问、OAuth 过期、MCP OAuth、AWS / Google Cloud / Foundry 认证
  • 网络与请求错误：网络不通、SSL 证书、请求被拒绝、上下文超限、安装错误
  • 命令行与插件错误：启动与命令行参数相关的错误，插件加载与市场错误
  • 工具、后台会话与配置警告：工具错误、后台会话错误、Wrapper 与 IDE 错误、回退与会话保存警告、配置警告，以及「回复质量似乎变差」时要检查什么

自动重试

Claude Code 在显示错误之前，会对暂时性失败做最多 10 次指数退避重试；对在 Claude 回复中途到达的失败，它并不总是重试。

会重试的：在 Claude 的任何回复流出之前到达的服务器错误、过载响应和请求超时；连接中断（连接在请求中途、Claude 完成任何回复（包括思考）之前断开时，用相同的退避重新发出请求）；由电脑睡眠导致的连接中断；停滞的响应流（响应头已到但 Claude 的回复一点都没来，或 Claude 思考完但还没开始任何文本或工具调用时，Claude Code 中止停滞的连接并至多重新发出一次请求）；API 一直不返回响应头的流式请求（在截止时间中止并最多重发一次）；临时的 429 限流（不包括网关的支出限额 429）；因输入加 max_tokens 超出上下文限制而被拒绝的请求（以减小的 max_tokens 重试，无法缩小时改为压缩）；Google Cloud Agent Platform 上过期或缺失的凭据，或在本机加载失败的 AWS 凭据（丢弃缓存的凭据并最多重试两次）；apiKeyHelper 脚本提供凭据时来自 Anthropic API 的 401 或 403（重新运行脚本并用新输出重试）。

不会重试的：TLS 证书验证失败（如 TLS 检查代理、缺少 NODE_EXTRA_CA_CERTS 证书包或证书过期，第一次尝试就报告以便你立即修复）；在 Claude 已完成一个文本块或工具调用之后、但回复结束之前到达的服务器错误、连接中断或流停滞（重新运行请求可能重复执行相同的工具调用，所以 Claude Code 保留 Claude 已完成的内容并显示 The response above may be incomplete）；在 Claude 完成回复之后到达的失败（保留完整回复并正常结束回合）；你的组织策略检查拒绝的请求（Enterprise 的推理 hooks 功能）。

重试时你看到什么：重试期间转轮在错误标签之后显示 Retrying in Ns · attempt x/y 倒计时；对你可以立即处理的失败（网络断了、TLS 握手失败、触及速率限制），标签点明具体原因。529 过载时倒计时下一行还会点明去哪里查服务状态（Anthropic API 是 status.claude.com，其他是消息里点名的提供商或网关主机）。响应流在请求仍未完成时 20 秒内没有数据到达，转轮会显示 Waiting for API response · will retry in … · check your network（此时请求还没失败）；数据恢复或重试成功后横幅自动消失，如果每次尝试都再次出现，把它当作网络问题。咨询 advisor 期间该横幅在 90 秒无数据后才出现。

调优重试行为

变量默认作用
CLAUDE_CODE_MAX_RETRIES10重试次数；v2.1.186 起上限 15，v2.1.199 起 CLAUDE_CODE_RETRY_WATCHDOG 提高默认值并去掉上限；在脚本里调低可以更快暴露失败
CLAUDE_CODE_RETRY_WATCHDOG未设置在 CI 等无人值守会话里设为 1，对 429 和 529 容量错误无限重试，而不是在 CLAUDE_CODE_MAX_RETRIES 次后失败；标准速度请求得到报告支出限额的 429 时立即失败
API_TIMEOUT_MS600000每请求超时（毫秒）；网络或代理慢时调高；它也限制 Claude Code 等待响应头的时间
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS未设置流式请求第一个响应字节的截止时间（毫秒），需要 v2.1.242 或更高版本

服务器错误的处理思路

这类错误大多来自推理提供商（Anthropic API 上是 Anthropic 的服务，Bedrock、Agent Platform、Foundry 或自定义网关上是该提供商端点背后的服务）。5xx 表示 API 内部的意外失败，不是你的提示、设置或账号造成的。代理、负载均衡器或网关返回 HTML 错误页时，消息显示状态码和页面标题（如 API Error: 502 Bad Gateway）。怎么做：到 status.claude.com 或消息里点名的提供商状态页查看有无进行中的事故；等一分钟后重发消息（原消息仍在对话里，长提示可以输入 try again 而不必重新粘贴）；错误持续而没有公告的事故时，运行 /feedback 让 Anthropic 用你的请求详情调查（/feedback 在你的环境里不可用时见官方「Report an error」）。Repeated 529 Overloaded errors 表示 API 在所有用户范围内暂时容量不足，Claude Code 已重试多次，通常是暂时的。

In this section