Anthropic 529 overloaded_error:含义以及如何处理它

当 API 暂时过载时,Claude API 返回 529,错误类型为 overloaded_error。 根据 Anthropic 的说法,当 API 在所有用户范围内经历高流量时,可能会发生这种情况。 你的请求没问题。 API 正忙,因此拒绝了该请求。 当组织超出其自己的速率限制时,则会返回 429。 响应正文的结构与所有其他 Claude API 错误相同:顶级的type为error,一个包含type和request_id的error对象,以及一个可提供给 Anthropic 支持团队的message。 有关详细信息,请参阅 Claude API 错误。

529、429 或支出上限:如何区分它们

Claude API 对于截然不同的问题,使用看起来相似的错误信息。 如果你等一等,有些问题会自行消失。 有一个要到下个月才会解除。

响应 error.type retry-after 含义 怎么办
529 overloaded_error 如果它在那里,请使用它 API 对所有用户均处于过载状态 稍后重试几次
429 rate_limit_error 是的 你的组织每分钟的请求数、输入令牌数或输出令牌数超出限制,或者增长过快并触及加速限制 retry-after指定的时长等待
429 rate_limit_error,其中 error.details.error_code 设置为 enforced_spend_limit_reached No 你的组织已达到其使用层级的月度支出上限 请勿重试。 使用将暂停,直到下个月第一天 00:00 UTC,或者直到您升级到更高等级。
400 invalid_request_error No 使用情况达到了你在组织或工作区上设置的支出限制 提高或取消限制

支出上限 429 与速率限制具有相同的错误类型,因此每隔rate_limit_error重试的代码会持续失败。 Anthropic 指出,在访问恢复之前,包括 SDK 的自动重试在内的重试都会失败。 有关详细信息,请参阅达到支出上限。

如何处理 529

  1. 在重试之前检查状态代码。 529和429需要不同的等待时间,而没有retry-after的429根本不需要重试。
  2. 遇到 529 时退避。 使用指数退避和随机抖动重试,并在几次尝试后停止。 如果响应有retry-after标头,则改为等待该标头指定的时长。
  3. 让 SDK 完成前几次重试。 官方 Anthropic SDK默认对连接错误、速率限制和 5xx 错误重试两次,使用指数退避,并在存在retry-after时遵循该标头。 你可以使用max_retries(TypeScript 中为maxRetries)更改次数。 当 SDK 用尽重试次数时,你的代码会收到该错误。
  4. 达到支出上限时停止重试。 如果 429 没有retry-after标头,告知用户并向你自己发出警报。
  5. 让用户随时了解情况。 将工作排入队列,稍后重试,或显示明确的“忙碌,在一分钟内重试”消息,而不是一般错误。

在 Python SDK 中,429 会引发anthropic.RateLimitError,任何 500 或以上的状态码(包括 529)都会引发anthropic.InternalServerError:

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

如何测试你的应用是否能处理 529

开发时很少看到 529。 这取决于来自每个 Claude API 用户的流量,因此你无法触发它。 测试的方式决定你是否在用户之前找到 bug。

Approach 你找到的内容 您错过的内容
等到投入生产 真实过载 所有情况,直到用户遇到它
在测试中模拟 API,或让编码代理编写模拟 错误分支是否会运行 Anthropic的实际状态代码和错误正文,以及 SDK 的重试策略。 你的应用还需要一个仅用于测试的开关来访问模拟。
调用真实 API,直到它失败 实际表现 你无法按需触发 529,也完全无法安全地触发支出上限
截获应用的实际流量并按需返回 529 和 429 状态码 实际 URL、实际 SDK 和重试策略,以及Anthropic自己的错误格式 你的应用无需做任何更改,因此它不会对你的代码进行隔离测试。 将单元测试保留用于该目的。

在你的 App 中试用

Dev Proxy会截获你的应用发往https://api.anthropic.com的请求,并以 Anthropic 的错误格式返回错误,而你的应用会继续调用真正的 URL。 下载预设,并使用它启动 Dev Proxy:

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"
Preset 它返回的内容
anthropic-throttling 随机返回 4 种 429 rate_limit_error响应之一(请求、输入令牌、输出令牌和加速限制)或 529 overloaded_error。 对于 429 和 529,开发代理会设置 retry-after,并在你的应用过早再次调用 API 时发出提示。
anthropic-random-errors 对 50% 的请求随机返回 Claude API 错误列表中的一种错误,包括 400、401、402、403、404、409、413、429、500、504 和 529

两个预设都不包含支出上限 429。 若要测试该路径,请将不带 retry-after 标头的响应添加到预设的 anthropic-errors.json 文件中:

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

若要使每个请求都失败,以便查看 SDK 在重试次数用尽时会发生什么情况,请使用 --failure-rate 100 启动开发代理。 有关详细信息,请参阅 更改请求失败率。 若要安装 Dev Proxy,请参阅 “设置 Dev Proxy”。

后续步骤

另请参阅