Claude API 报 529 overloaded_error（Overloaded）：原因和处理办法

一句话答案

HTTP 529、"type": "overloaded_error"，意思是 Claude API 暂时过载。Anthropic 的 错误说明 里写得很清楚：529 出现在所有用户的流量都很高的时候。它不是你的限流，不是你设的消费上限，也不是 Claude 订阅的额度，所以账号这边没什么要改的。

有用的做法：

• 退避重试。 官方 SDK 默认会对 5xx 错误自动重试 2 次；能等的任务可以把重试次数调高。
• 看 status.claude.com 有没有容量相关的公告。
• 换一个模型。 在 Claude Code 里运行 /model。Claude Code 文档说容量是按模型分别计算的，一个模型过载时，换个模型往往就能接着用。
• 配好备用模型，下次自动切：Claude Code 里配 fallbackModel，自己的代码里在重试逻辑中加第二个模型。

报错长什么样

API 里。 错误体是 Claude 标准的 error 对象。流式请求中，这个错误也可能在已经返回 200 之后以事件的形式出现。下面是 Anthropic 流式文档 里的例子：

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

非流式请求会直接收到 HTTP 529，错误对象相同，另外带一个 request_id。

Claude Code 里。 Claude Code 会先自己重试，重试用完才显示错误。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 可能直接提示你换模型，比如 Opus is experiencing high load, please use /model to switch to Sonnet。如果你是通过网关或云厂商用 Claude Code，最后一句不会写 status.claude.com，而是写那家厂商或网关的地址，去看那边的状态页就行。

529 和 429、500、用量上限的区别

这几个在日志里长得像，处理方法不一样：

Anthropic 文档里的两个细节：

• 529 不占你的额度。Claude Code 错误说明里专门写了这一点。
• 你自己的流量突然暴涨，触发的是加速限制（acceleration limits），返回的是 429，不是 529。Anthropic 建议流量逐步爬升。如果只在流量猛增后才报错，先按 429 的思路排查。限流相关的内容见 Claude Code 限额与配额管理。

在自己的代码里处理

1. 让 SDK 重试，并把次数调高。 官方 SDK 会对连接错误、限流和 5xx 错误做指数退避重试，默认 2 次。批处理任务可以把 max_retries 调大。
2. 按类型捕获过载错误。 Python SDK 对 529 抛出 anthropic.OverloadedError。捕获这个类型，别去匹配错误信息的文字。
3. 准备第二个模型。 一个模型重试仍然失败，就把请求发给另一个模型。
4. 处理流里的错误。 返回 200 不代表流一定能跑完。收到带 overloaded_error 的 error 事件，按 529 处理，重新发请求。
5. 记下 request ID。 每个响应都有 request-id 响应头，联系 Anthropic 支持时带上。

import anthropic

client = anthropic.Anthropic(max_retries=5)

MODELS = ["claude-sonnet-5", "claude-haiku-4-5"]  # 主模型在前，备用在后


def ask(prompt: str):
    last_error = None
    for model in MODELS:
        try:
            return client.messages.create(
                model=model,
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
        except anthropic.OverloadedError as e:  # HTTP 529
            last_error = e  # 这个模型的重试已用完，换下一个
    raise last_error

在 Claude Code 里处理

Claude Code 遇到过载等临时错误，会先做最多 10 次指数退避重试，再把错误显示出来。所以看到报错时，多等一会儿仍然是主要办法。下面这些设置也有帮助：

• 换模型。 运行 /model 换一个。Claude 桌面 App 的 Code 标签页或 Cowork 里，用模型选择器切换。
• 配置备用模型链。 主模型过载或不可用时，Claude Code 可以在当前这一轮切到备用模型：

claude --fallback-model sonnet,haiku

想每次会话都生效，在设置里加 fallbackModel：

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

备用模型链只在过载、不可用和其他不可重试的服务端错误时切换，鉴权、计费、限流错误不会触发切换（见 模型配置）。

• 让无人值守的任务挺过去。 CI 或长时间自动运行的任务，可以设 CLAUDE_CODE_RETRY_WATCHDOG=1。这样 Claude Code 会对 429、529 这类容量错误一直重试，不会在 CLAUDE_CODE_MAX_RETRIES 次（默认 10 次）后放弃。
• 拉长重试间隔。 v2.1.292 及以上版本，可以用 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS（默认 500，最大 32000）设置 529 重试的起始间隔。

通过 TeamoRouter 调用 Claude

换一个接入地址，并不会让过载的模型多出容量，我们也不承诺通过 TeamoRouter 就不会遇到 529。它提供的是：一个按量付费的账号，覆盖多个模型系列。

TeamoRouter 是一个 API 网关，一个 Key 可以调 Claude、GPT、Gemini、DeepSeek。Claude 走原生 Anthropic 协议（/v1/messages），GPT 等其他模型可以走 OpenAI 兼容的 /v1/chat/completions。换 Claude 模型还不够时，把任务挪到别的模型系列，只要改模型名，不用再开新账号。没有订阅，按用量付费。

1. 在 TeamoRouter 控制台 创建 API Key，Key 以 sk-teamo- 开头。
2. 充值，最低 $5。 充值弹窗支持银行卡；也可以点 「USDT支付」，用 USDT、USDC 或 ETH，从币安、OKX 等交易所 App 转账——收银台会按金额显示可用网络（BEP20 从 $5 起就能用），不用装钱包插件。步骤见 用 USDT 充值。
3. 让 Claude Code 指向 TeamoRouter（macOS / Linux）：

export ANTHROPIC_BASE_URL=https://api.teamorouter.com
export ANTHROPIC_AUTH_TOKEN="你的 TeamoRouter API Key"
claude

Base URL 后面不要加 /v1。用 Anthropic SDK 时，传 base_url="https://api.teamorouter.com" 和你的 TeamoRouter Key。可用的模型 ID 用 GET /v1/models 查。Windows 命令和模型设置见 安装与配置 Claude Code，各协议的调用方式见 API 接入指南。

常见问题

529 会占我的限流额度或 Claude 套餐额度吗？ 不会。Anthropic 的 Claude Code 文档写明，529 不是你的用量上限，也不计入额度。

过载一般持续多久？ 错误说明里没有给出典型时长，Claude Code 的提示只说通常是暂时的。可以看 status.claude.com 有没有进行中的事件，同时退避重试或先换模型。

为什么一个模型报 529，另一个却正常？ Claude Code 错误说明里写了，容量按模型分别计算。所以官方推荐的办法就是 /model 换模型或配置备用模型链。

升级套餐或用量等级能避免 529 吗？ Anthropic 文档把 529 描述为所有用户的流量过高，而不是你账号上的限制。升级等级提高的是限流额度，那是 429 的问题。

延伸阅读

• Claude Code 限额与配额管理
• Claude Code 提示「Prompt is too long」怎么办
• 安装与配置 Claude Code
• 用 USDT 充值 Claude API