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