Claude Overloaded 报错（529）怎么解决：网页版、Claude Code 与 API 修复指南

一句话结论： Overloaded（529 / overloaded_error）代表 Anthropic 服务器因全网高并发流量暂时满载——这不是你的配置问题或个人/组织用量上限，不会计入你的配额（quota），通常等待几分钟即可恢复。

现在该怎么做

1. 等 1–5 分钟再试（不要狂点重试）： 在 Claude Code 中，客户端在显示报错前已经自动重试了多次，立即连续点击或重跑命令不会加快恢复。
2. 在 Claude Code 中用 /model 切换模型： 容量按模型独立统计。若 Opus 过载，可在交互式会话中运行 /model 切换到 Sonnet（或在非交互模式下传入 claude --fallback-model sonnet,haiku）。
3. 若过载持续，通过 UniRoute 转发请求： 跳转到下方 UniRoute 接入章节，将请求调度到当前最稳定的可用区域容量，并在流式传输开始前跨上游账号自动重试 529。

---

1. 使用 Claude.ai 网页版或桌面端

根据 Claude Code 错误排查文档，当特定模型（如 Claude Opus）在网页端或桌面端遭遇高并发负载时，桌面应用会提示：

Opus is experiencing high load. Switch to Sonnet.

网页端 / 桌面端恢复步骤：

1. 查看上方的实时状态卡片（或访问 https://status.claude.com），确认 claude.ai 组件是否有正在处理的故障。
2. 在对话模型选择器中切换模型： 因为容量是按模型独立统计的，当 Opus 满载时，切换到 Claude Sonnet 往往仍可正常响应。
3. 等待 1–5 分钟后再重发消息，无需退出登录或清空当前会话。

---

2. 使用 Claude Code

根据 Claude Code 错误排查文档，当 API 因所有用户的整体高流量而暂时满载时，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 Opus 负载过高时，CLI 会提示：

Opus is experiencing high load, please use /model to switch to Sonnet

Claude Code 官方处理步骤：

1. 查看 https://status.claude.com（或本文顶部的实时状态组件）。
2. 等待几分钟后再试： HTTP 529 不是你所在组织的用量上限，也不会计入你的配额（quota）。
3. 运行 /model 切换模型： 容量按模型独立统计，可在交互式会话中输入 /model 切换到 Sonnet（非交互模式可使用 claude --fallback-model sonnet,haiku）。若官方容量持续过载，可将 Claude Code 接入 UniRoute。

---

3. 使用 Claude API（开发者方案）

当 Anthropic API 在某个模型上遭遇全网高并发流量（high traffic across all users）时，服务端会返回 HTTP 529 状态码，错误类型为 overloaded_error（在 Anthropic API 错误文档 表格中描述为 "The API is temporarily overloaded."，具体的 error.message 文本可能有所不同）。

3.1 识别 API、Claude Code 与网关下的 HTTP 529 及 overloaded_error 报错信息

过载错误可能发生在 HTTP 响应头建立之前、HTTP 200 流式传输启动之后，或推理网关耗尽上游尝试之后。通过具体的报错文本即可区分错误发生的位置。

A. Anthropic 官方 Messages API 直连响应（POST /v1/messages）

当请求因全网高流量被拒绝时，Anthropic 会返回 HTTP 529 状态码、request-id 响应头以及官方文档定义的 overloaded_error JSON 错误结构（非实抓响应报文；error.message 文本可能有所不同，"req_..." 为占位符）：

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  },
  "request_id": "req_..."
}

B. Claude Code CLI（官方文档提示 vs 自定义 Base URL 的非交互模式输出）

Claude Code 在遇到 529 时会先执行指数退避重试，重试耗尽后输出报错：

• 官方文档记载的连续 529 报错信息：

  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 Opus 负载过高时）：

  Opus is experiencing high load, please use /model to switch to Sonnet
  

• 配置自定义 ANTHROPIC_BASE_URL 时的非交互模式（claude -p）输出（在我们使用 Claude Code 2.1.295 针对返回 "message": "Overloaded" 的本地模拟服务测试中实测所得）：

  API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:<port>).
  

C. HTTP 200 OK 建立后的流式中途错误（SSE）

根据 Anthropic 流式错误事件文档，当开启流式输出（"stream": true）时，错误可能发生在初始 HTTP 200 响应建立之后，并以 Server-Sent Events（SSE）错误事件的形式送达。

在 Claude Code（v2.1.199+）中，响应生成中途发生服务端错误时会提示：

API Error: Server error mid-response. The response above may be incomplete.

D. 经过 UniRoute 网关（所有上游尝试耗尽后的 HTTP 503）

当请求通过 UniRoute（说明：我们自研的网关）转发，且某个上游账号在流式传输开始前返回 529 时，UniRoute 可以将该账号暂停一段冷却时间（冷却时长可配置，本文未核查生产环境的具体配置），并尝试同一模型的其他上游账号。只有当所有流前上游尝试均已用尽时，UniRoute 才会返回 HTTP 503：

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Upstream service overloaded, please retry later"
  }
}

在指向自定义 Base URL 的 claude -p 模式下，收到上述网关 503 响应体时终端输出为：

API Error: 503 Upstream service overloaded, please retry later. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:<port>).

3.2 诊断对比表：529 vs 429 vs 400 vs 500 vs 504 vs 503

在修改重试配置之前，请先对照 HTTP 状态码和错误 type，确认你遇到的是共享模型高流量（529）还是组织自身的配额/消费限制（429/400）：

3.3 Claude Code 的 529 退避重试与 --fallback-model 切换实测

我们的测试方法（How We Tested）

在 2026-10-18，我们在 darwin arm64 环境下使用 Claude Code 2.1.295 的非交互打印模式（claude -p "reply OK"），连接本地 127.0.0.1 上的模拟 HTTP 服务进行测试。模拟服务分别返回 HTTP 529（{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}）与 HTTP 503（{"type":"error","error":{"type":"overloaded_error","message":"Upstream service overloaded, please retry later"}}）。本次测试未发起任何真实外部 API 调用，费用为 $0。它用于验证 Claude Code 2.1.295 客户端二进制程序的重试调度与备用模型切换行为，但不代表我们复现了真实的 Anthropic 线上 529 故障，也不衡量生产环境的故障发生率。

客户端重试与备用模型切换实测结果（Claude Code 2.1.295，2026-10-18）

对 --fallback-model 配置的启示

在我们使用 Claude Code 2.1.295 的测试中，客户端在主模型出现连续 3 次 529 后才切换到备用模型；当仅允许 1 次重试（CLAUDE_CODE_MAX_RETRIES=1）时，客户端从未发生模型切换。因此，如果你依赖备用模型自动切换，过低的重试上限可能导致请求在切换发生前就已经结束——在我们的测试中，仅允许 1 次重试是不够的。

3.4 配置 Claude Code 重试参数与备用模型（fallbackModel）

A. 调整重试次数与 529 退避延迟

Claude Code 提供以下环境变量来控制重试次数与 529 指数退避延迟：

# 默认重试 10 次（v2.1.186+ 上限为 15）。
# 如果你依赖备用模型切换，请勿将此值设得过低（在我们的测试中设为 1 未能触发切换）。
export CLAUDE_CODE_MAX_RETRIES=5

# 529 过载指数退避的基础延迟（默认 500ms，上限 32000ms，v2.1.292+）
export CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=1000

# 529 单次退避等待的最大延迟上限（默认 32000ms，上限 64000ms，v2.1.296+）
export CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=32000

B. 无人值守任务（CLAUDE_CODE_RETRY_WATCHDOG）

对于无人值守的 claude -p 任务，可以启用 CLAUDE_CODE_RETRY_WATCHDOG：

export CLAUDE_CODE_RETRY_WATCHDOG=1
# 可选（v2.1.295+）：限制每个 API 请求在等待 429/529 恢复时所花费的最大毫秒数
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=300000

claude -p --fallback-model sonnet,haiku "运行测试套件并汇总失败原因"

启用 CLAUDE_CODE_RETRY_WATCHDOG=1 后，Claude Code 会无限期重试 429 和 529 容量错误，而不是在达到 CLAUDE_CODE_MAX_RETRIES 次尝试后失败（在 v2.1.199+ 中，它还会将其他瞬态错误的默认重试上限提升至 300 次）；但若遇到消费上限触发的 429，仍会立即终止报错（v2.1.239+）。在 v2.1.295+ 中，CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 用于限制每个 API 请求在等待 429/529 时最多花费的时间。

C. 在 .claude/settings.json 或命令行中配置 fallbackModel

在非交互模式（claude -p）中，可通过命令行参数指定备用模型链：

claude -p --fallback-model sonnet,haiku "汇总最近的提交记录"

也可以按照官方文档示例，在 .claude/settings.json 中配置 "fallbackModel"：

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

根据 Claude Code 官方文档：备用模型切换在**当前回合（current turn）**生效；降级链最多支持 3 个模型；当命令行参数 --fallback-model 与配置文件同时存在时，命令行参数优先。

3.5 官方 Anthropic SDK（TypeScript 与 Python）的重试行为

如果你在代码中通过官方 @anthropic-ai/sdk（TypeScript）或 anthropic（Python）SDK 调用 API，官方客户端默认会对连接错误（connection errors）、速率限制（rate limits）以及 5xx 服务端错误采用指数退避策略自动重试 2 次，并遵循 retry-after 响应头。

下方示例使用与 Claude Code 接入指南 相同的 Base URL（https://api.uniroute.app）；我们在本文中未实测该 SDK 调用路径。存放 API Key 的环境变量名称可由你自行命名：

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MY_API_KEY, // 环境变量名可自行定义
  baseURL: 'https://api.uniroute.app',
  maxRetries: 4, // 默认值为 2
});

Python 示例：

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["MY_API_KEY"],  # 环境变量名可自行定义
    base_url="https://api.uniroute.app",
    max_retries=4,  # 默认值为 2
)

如果 SDK 客户端已经启用了 maxRetries，请避免在业务代码外层再嵌套一层自定义重试循环，以免在过载期间成倍放大上游请求次数。

---

4. 过载持续时通过 UniRoute 接入 Claude Code 或 API

说明（Disclosure）： UniRoute 是我们自研的统一 AI API 网关。使用 UniRoute 并不能保证零过载，也无法阻止响应流启动后的中途报错。

官方 Claude 529 过载取决于全球各区域服务器的总负载。当你将 Claude Code 或 Anthropic SDK 接入 UniRoute 时，UniRoute 会在保持相同 Claude 模型 ID 的前提下，跨区域调度到当前最稳定的可用容量：

1. 流式传输开始前的账号容灾切换： 如果某个上游账号在尚未向客户端发送任何流式数据前返回 529，UniRoute 可以将该账号暂停一段冷却时间（冷却时长可配置，本文未核查生产环境的具体配置），并自动尝试同一模型下的另一个上游账号。
2. 当所有上游尝试均已耗尽： 只有当你的请求在流式输出前用尽了所有上游尝试时，UniRoute 才会返回 HTTP 503，其 error.type 为 "overloaded_error"，消息为 "Upstream service overloaded, please retry later"。
3. 流式传输开始之后： 一旦 HTTP 200 响应流已经开始向客户端发送数据，UniRoute 无法在响应中途切换上游账号或重放请求。

价格与渠道自动切换： 截至 2026-10-27，折扣渠道可用时，Anthropic Claude 模型低至官方 API 价的 42%（例如 UniRoute 价格页上 Claude Sonnet 5.5 输入/输出每百万 Token 为 $0.84 / $4.20，官方为 $2.00 / $10.00；Claude Opus 5.5 为 $1.68 / $8.40，官方为 $4.00 / $20.00）；折扣渠道不可用时，会自动切到与官方同价的标准渠道（渠道说明）。

使用 uniroute-setup 配置 Claude Code

先在 UniRoute 控制台创建 API Key，随后在终端执行以下命令（要求 Node.js 22+；终端会隐藏输入提示你填入 Key）：

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure claude --model MODEL_ID --dry-run
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure claude --model MODEL_ID

手动配置 .claude/settings.json 及验证步骤详见完整的 Claude Code CLI 配置教程。

---

5. 重试前核查清单：状态页与用量记录

在重新运行因报错中断的 Claude Code 命令前，建议按以下步骤核查：

1. 查看 https://status.claude.com： Anthropic 官方状态页分别独立展示 claude.ai、Claude Console (platform.claude.com)、Claude API (api.anthropic.com) 与 Claude Code 的运行状态。
2. 流中报错后先检查本地工作区： 如果终端提示 API Error: Server error mid-response. The response above may be incomplete.，请先运行 git status 和 git diff，确认中断前有哪些文件改动或命令已经执行。
3. 重发前核对用量记录： 在重新发送请求前，请先在你的 UniRoute 用量记录中核查该笔请求的状态；若需整理故障信息提交工单（包括私下保存 request-id），请参考我们的 Claude Code API Error 500 排查指南。

---

6. 常见问题解答（FAQ）

1. HTTP 529 报错会消耗我的配额或产生费用吗？

不会。根据 Claude Code 错误排查文档，529 不是你的用量限制，也不会计入你的配额（quota）——它仅表示 API 当前面临全网高流量。如果请求在返回 HTTP 200 并开始流式输出后中途失败，请在重发前核对你的用量记录。

2. 529 过载一般会持续多久？

Anthropic 官方并未公布 529 容量高峰的固定持续时长；官方报错提示指出该情况“通常是暂时的（usually temporary）”，建议稍后重试，若持续出现则查看 https://status.claude.com。切换模型（/model 或 --fallback-model）可能有所帮助，因为容量是按模型独立统计的。

3. HTTP 529 是因为我所在组织的速率限制触发的吗？

不是。组织的速率限制、短时流量陡增限制以及月度消费上限会返回 HTTP 429（rate_limit_error），而用户自行配置的消费限额会返回 HTTP 400（invalid_request_error）。HTTP 529（overloaded_error）是由所有用户的整体高并发流量引起的。

4. 为什么 Claude Code 会提示 "check your inference gateway"？

当 ANTHROPIC_BASE_URL 被配置为自定义网关或本地代理地址（而非 Anthropic 默认官方地址）时，Claude Code 在非交互打印模式下的报错信息末尾会附带 If it persists, check your inference gateway (<host>)，以便你确认是哪个上游地址返回了 529 或 503。

5. "overloaded"（过载）等于 Claude 彻底宕机吗？

不一定。容量是按模型独立统计的，因此其他模型（例如 Sonnet）可能仍有可用容量（Claude Code 也会提示通过 /model 切换）；同时 https://status.claude.com 会将 claude.ai、Claude Console (platform.claude.com)、Claude API (api.anthropic.com) 和 Claude Code 作为独立组件分别展示状态。