Claude Code 529 Overloaded 报错：原因、重试设置与排查

Wokey Team · 2026-09-24

结论先说： 529 的意思是上游模型此刻算力不够（overloaded），和你的余额、额度、API Key 都没有关系。Claude Code 显示这条报错之前已经自动重试过好几次。最快的办法是用 /model 换一个模型，因为容量是按模型计算的；不着急的话，等几分钟再发。

报错原文

Claude Code 里看到的是：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Claude Code 官方文档对它的说明有三点：

• 这是所有用户共同遇到的临时容量不足。
• 显示这条消息之前，Claude Code 已经重试过多次。
• 529 不是你的用量限制，也不计入你的额度。

通过 ANTHROPIC_BASE_URL 接网关时，最后一句不会再指向 status.claude.com，而是写上网关的域名。

通过 Wokey 时，529 从哪来

Wokey 自己不会产生 529，这个状态码一定来自上游模型。Wokey 这一层的处理分三步：

1. 上游返回过载（例如 Anthropic 的 overloaded_error）时，Wokey 先把这次请求换到同一模型的另一个上游通道重试，你这边感知不到。

2. 重试的通道也过载，Wokey 才把上游的状态码原样交给你：HTTP 状态仍是 529，响应体是 Wokey 的统一错误格式，message 是上游的原话：

   {"error":{"code":"upstream_unavailable","message":"Overloaded","type":"invalid_request_error"}}
   

3. 如果回复已经开始输出后才过载，错误会以流内的 error 事件出现，而不是 HTTP 529。

所以通过 Wokey 看到 529，意味着同一个模型的多个上游通道同时过载，通常是官方侧的使用高峰。这类响应不带 Retry-After 头，客户端会按自己的退避策略重试。

和其他状态码区分

只有 529 和 503 是「上游这会儿忙不过来」，其他几个都要你这边处理。

怎么处理

1. 等一会儿再发。 过载通常几分钟内就会恢复。Claude Code 的自动重试已经覆盖了短时间的抖动。

2. 用 /model 换模型。 容量按模型计算，Opus 过载时 Sonnet 往往还能用。在会话里运行 /model 选另一个模型即可，不用退出。

3. 无人值守的长任务，调高重试。 在 ~/.claude/settings.json 的 env 里设置：

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 会让 Claude Code 对 429 和 529 无限重试，两次之间最长退避 5 分钟，适合晚上挂着跑的任务。
• 只想多重试几次时，改用 CLAUDE_CODE_MAX_RETRIES。默认是 10，最大 15。

4. 自己写代码调用时，给 529 留重试。 Anthropic 官方 SDK 默认会对 5xx（含 529）重试 2 次。批量任务可以把 max_retries 调大，并在外层再加一层指数退避。

Codex 里遇到 529

Codex 会把 5xx（含 529）当作可重试错误：

• HTTP 层默认重试 4 次，由 provider 的 request_max_retries 控制。
• 流式层再重试最多 5 次，由 stream_max_retries 控制。
• 都失败后，报错以 unexpected status 529 开头，后面附上响应体。

响应体里的 code 是 upstream_unavailable，就是上面说的上游过载。处理方法一样：等一会儿，或在 config.toml 里换一个模型。Codex 的完整配置见 Codex config.toml 指南。