Claude API 中的 529 overloaded_error——含义及应对方法

529 是 Claude 唯一一个不是由你的代码造成的错误：Anthropic 自身过载。你无法修复它，但可以妥善吸收影响。这意味着要耐心重试、准备备用模型，并且绝不能立即重复尝试来放大事故。

错误

响应（HTTP 529）

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

原因和解决方法一览

原因	解决方法
提供商容量饱和（发布日、区域性事故）	使用带抖动的指数退避。请查看提供商的状态页面，而不是重新部署。
部分事故期间你的流量峰值下降了	将作业分批分发；等待十分钟通常就能解决问题。
循环立即重试	立即重试会成倍增加负载，延长所有人的事故，包括你自己的事故。

像一个负责任的用户一样重试

将 529 当作没有 retry-after 标头的 429 处理：从约 2 秒开始进行带抖动的指数退避，上限设为 30–60 秒，约 5 次尝试后放弃并将工作排队。处理 429 的同一段代码也适用于 529。

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

切换模型，而不是崩溃

对于对延迟敏感的路径，请设置备用模型：在同一系列内切换（Sonnet → Haiku）时行为较为相似；跨提供商切换（Claude → GPT）则可以应对完整的事故。在兼容 OpenAI 的端点上，这只是替换一个字符串。

failover.py

PREFERIDOS = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

不要混淆 529、429 和 402

429 表示你超过了自己的限制（服务器运行正常）。529 表示服务器过载（你的配额正常）。402 表示余额不足。三者在日志中很相似，但修复方式完全不同：只有 429 和 529 应该重试。

如果你通过 Kunavo 调用

在 Kunavo 中，同一个多模型目录由一个密钥和一个钱包统一支持，因此上例中的跨提供商故障转移只需替换模型名称——不需要第二个账户或第二次注册。失败的请求不会收费。容量和价格是两个不同的问题；关于后者，令牌费率请参阅我们的 Claude API 价格指南.

常见问题

529 错误是我的责任吗？

不是。这是提供商一侧的容量问题。你唯一需要负责的是不要放大问题（使用带抖动的退避），并在事故持续时间超过延迟预算时准备好迁移目标。

529 和 429 有什么区别？

429 表示你超出了限制；529 表示服务器过载。两者都可以重试，但通常只有 429 会附带 retry-after 提示。

529 请求会收费吗？

不应收费——该请求没有生成令牌。在 Kunavo 中，失败的请求不会从余额中扣除。