Claude API 529 Overloaded 错误：原因与处理方法

Claude API 返回 529、错误类型为 overloaded_error，意思是 Anthropic 的 API 在所有用户层面暂时满载。它不是你的 key、请求体或自身限速出了问题。正确做法是指数退避重试；如果频繁出现，就切换到另一个模型，或者把不急的任务移出实时链路。

下文事实均出自 Anthropic 官方文档（Claude API 错误页、流式输出指南、SDK 参考文档、Claude Code 错误参考），核实日期 2026-09-24。

Claude API 529 overloaded 到底是什么意思

Anthropic 的错误页把 529 列为 overloaded_error，说明只有一句：API 暂时过载。同一页面还附了一条警示：当 API 在所有用户层面流量很高时，就可能出现 529。

最后这半句就是全部诊断。529 描述的是服务的状态，而不是你账户的状态。它不是你的请求引起的，你改请求里的任何东西，下一次也不会因此变好——能解决它的只有时间，或者把请求发到还有余量的地方。

和所有 Claude API 错误一样，响应体是 JSON，顶层 error 对象里一定有 type 和 message，外加一个 request_id：

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

每次都把 request_id 记进日志。官方文档要求就具体请求联系支持时提供它，这也是把你日志里的失败和服务端的失败对上号的唯一可靠办法。

529、429、500、504：看错误类型，不要只看数字

这四个最容易混，因为它们看起来都像「API 没响应」，但各自的处理方式不同：

状态码	错误类型	问题在哪一侧	该怎么做
429	`rate_limit_error`	你的组织撞到了速率限制或支出上限	按 `retry-after` 头等待；如果没有这个头，先判断是不是支出上限而非限速
500	`api_error`	Anthropic 系统内部出现意外错误	指数退避重试；持续出现就带 request ID 联系支持
504	`timeout_error`	请求在处理中超时	长请求改用流式输出或 Message Batches API
529	`overloaded_error`	API 在所有用户层面满载	退避重试，然后切换兜底方案

有两个坑值得单独说：

容量问题也可能以 429 的形式出现。 Anthropic 的错误页和速率限制页都提到：如果你所在组织的用量陡增，可能因为 API 的加速度限制（acceleration limits）收到 429。这种情况的修法在你自己这边：逐步放量，保持稳定的使用模式。上线跑批任务或新功能时，头几分钟的 429 可能是放量太猛，而不是稳态限额。三条限额怎么计量，见 Anthropic API 速率限制说明。
没有 retry-after 的 429 不是限流。 按速率限制文档的说法，档位支出上限触发的 429 不带 retry-after 头，在恢复访问之前会一直失败。对它重试纯属浪费，把它当 529 处理的重试循环会一直空转。

如果报的是 400 而不是以上任何一个，那是请求本身的问题，与容量无关——见 Claude API 400 错误排查。

529 会以哪几种形态出现

同一种状况会以三种不同的形态出现，只处理第一种的代码会漏掉另外两种。

普通请求直接返回 HTTP 529。 请求返回 529 和上面那段响应体，这是最好处理的情况。

已经返回 200 的流里出现错误事件。 Anthropic 的流式输出指南写明：高峰期你可能在事件流里收到 overloaded_error，它在非流式场景下通常对应 HTTP 529。它以 event: error 行的形式到达，JSON 结构相同。错误页也明确说，200 之后出现的这类错误不走标准错误处理机制——你的 HTTP 状态码检查早就通过了。如果你自己解析原始事件流，就需要为 error 事件单独写分支，并决定已经收到的那部分输出怎么处理。事件类型详见 Claude API 流式输出指南。

Claude Code 里的「API Error: Repeated 529 Overloaded errors」。 Claude Code 的错误参考说明，显示这条消息之前它已经重试过多次；529 不是你的用量上限，也不计入你的额度。官方给出的处理方式是：查看 status.claude.com、过几分钟再试，或者运行 /model 换一个模型继续工作，因为容量是按模型分别计算的。

官方 SDK 已经替你做了什么

自己写重试循环之前，先弄清楚默认就有什么。根据 Python 和 TypeScript SDK 参考文档，SDK 默认会对部分错误自动重试 2 次，采用较短的指数退避。连接错误、408、409、429 以及所有 500 及以上的错误都会重试——529 包含在内。Python SDK 把 529 抛成 InternalServerError，这是它给所有 500 及以上状态码用的异常类。

重试次数可以配置：Python 里是 max_retries，TypeScript 里是 maxRetries，可以设在客户端上，也可以按单次请求设置；设成 0 就关闭自动重试。

对于用户正在前台等结果的对话请求，这个默认值是合理的起点。但在持续性的容量事件里，它对后台任务通常太短，而且对流中途出现的错误完全不起作用。

扛得住高峰的重试策略

如果要把重试次数调到 SDK 默认值以上，就集中在一处、有意识地做。可靠的模式是：

指数退避加随机抖动。 每次等待时间翻倍，再加一段随机量，避免成千上万个同一时刻失败的客户端又在同一时刻一起重试。
单次等待和总时长都要封顶。 给单次等待设上限（比如 30 秒），也给整个重试预算设上限，避免一个请求无限期挂着。
只重试该重试的。 529、500 和连接错误可以重试；400、401、403、404 永远不重试；429 只在 retry-after 给出的时间之后重试，没有这个头就不要重试。
只保留一层重试。 如果加了自己的循环，就把 SDK 的重试次数设成 0，否则你的每一次尝试都会变成三次。

import random
import time

import anthropic

client = anthropic.Anthropic(max_retries=0)  # 重试由下面这个函数统一负责

RETRYABLE = {500, 529}

def create_with_backoff(models, max_attempts=6, **kwargs):
    delay = 1.0
    for attempt in range(max_attempts):
        # 前几次留在首选模型，靠后的尝试才换到下一个模型
        model = models[min(attempt // 3, len(models) - 1)]
        try:
            return client.messages.create(model=model, **kwargs)
        except anthropic.APIStatusError as err:
            if err.status_code not in RETRYABLE or attempt == max_attempts - 1:
                raise
            time.sleep(delay + random.uniform(0, delay))
            delay = min(delay * 2, 30)

message = create_with_backoff(
    ["claude-sonnet-5", "claude-haiku-4-5"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "总结一下这张工单。"}],
)

模型列表是大多数重试循环漏掉的那一块。容量事件期间反复重试同一个模型，等于赌这次事件会在你的重试预算内结束；换模型则是利用 Claude Code 错误参考里写明的事实——容量按模型分别计算。至于小一档的模型能不能接受，是产品层面的决定，应该明确做出，而不是让兜底逻辑悄悄改变回答质量。

对于流式请求，中途收到 overloaded_error 通常意味着丢弃已收到的部分输出、重新发送整个请求，因为 API 没有提供从断点续传流的方式。

光靠重试不够的时候

如果 529 是频繁出现而不是偶发，解法就在架构层面：

先看 status.claude.com。 这是官方状态页，Claude Code 自己的 529 提示里也指向它。如果正在发生容量事件，正确的做法是优雅降级、等待，而不是反复调重试参数。
把能等的任务移出实时链路。 夜间数据加工、评测、批量分类应该走 Message Batches API——Anthropic 的服务层级文档把 Batch 描述为适合可以等待、或者放在常规容量之外更有利的异步工作流。限制条件见 Claude API 批处理说明。
长输出用流式。 官方建议长时间运行的请求（尤其超过 10 分钟的）使用流式 Messages API 或 Batches API。这不能防止 529，但能避免长请求在 529 之外再叠加超时。
Priority Tier 已经停售。 服务层级页面说明，Priority Tier 会优先处理请求，即使在高峰期也能尽量减少「服务器过载」错误；但其容量承诺已不再对外销售，已有承诺的组织可以用到合同结束。需要保障容量的，页面指引联系 Anthropic 销售。

通过网关或中转调用时

如果你的请求要经过 API 网关、中转或代理，529 可能来自两个地方：一是 Anthropic API 原样传回，二是网关自身的容量。你最终看到什么，还取决于网关怎么映射错误——有的把 529 和 overloaded_error 原样透传，OpenAI 兼容层则可能把它转换成自己的格式。

三个检查能让问题保持可诊断：

读错误的 type，不要只看状态码，并记下你拿到的是哪一方的 request ID——网关的、Anthropic 的，还是两者都有。
只在一层重试。 如果网关已经对上游 529 做了重试，客户端又重试一遍，一次过载就会在容量最紧的时刻被放大成一大波请求。
拿直连请求做对照。 如果网关返回 529，而 status.claude.com 显示正常、直连请求也能成功，那容量问题出在网关这一侧。

依赖一个网关之前该核对哪些点，见 Claude API 中转指南。

常见问题

Claude API 529 错误是我这边的问题吗？

不是。Anthropic 错误页把 529 描述为 API 暂时过载，并说明它可能在所有用户层面流量很高时出现。你的 key、请求体和速率限制都不是原因。

遇到 529 该不该重试？

该重试，用指数退避加随机抖动。官方 SDK 默认已经对 5xx 错误重试 2 次；后台任务可以调高次数，529 持续出现时再加一个兜底模型。

529 会计入我的速率限制或额度吗？

Claude Code 的错误参考写明，529 不是你的用量上限，也不计入你的额度。它是容量信号，和你自己的限额用尽时返回的 429 是两回事。

529 和 429 有什么区别？

429 表示你的组织撞到了速率限制或支出上限，通常带 retry-after 头；529 表示服务对所有人都满载了。例外是：你自己的用量陡增可能触发加速度限制导致 429，修法是逐步放量。

把多模型接入收在一处

按模型兜底，前提是你的技术栈里换模型足够便宜。ROIBest AI 提供 OpenAI 兼容端点，一把 key 覆盖多个模型家族，所以兜底时换模型只是改一个参数，而不是新做一次接入；按 key 的用量记录也能看出每个请求实际由哪个模型处理。