故障排查 · 核到 2026-10-20

529 Overloaded 到底意味着什么

截至 2026-10-20 的官方口径:529 Overloaded 指的是 Claude 的 API 容量暂时满载,官方错误文档写明这是对所有用户同时出现的容量状态,不是你的用量限额,也不计入配额。这次核对还补上了官方文档里的重试参数默认值:CLAUDE_CODE_MAX_RETRIES 默认 10(2.1.186 起上限 15),529 重试的基础延迟默认 500 毫秒(CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS,可上调到 32000),退避上限默认 32000 毫秒(CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS,可上调到 64000)。改代码没用,改重试策略才有用。

更新于 2026-10-20

一把 Key 调用 Claude、GPT 与主流国产模型,按 token 计费,几分钟上手。

#Claude 529#529#Overloaded#退避与重试上限

四个要点

529

厂商侧拥塞

服务端整体容量紧张时返回,与你的密钥额度、参数、请求体都无关。官方错误文档写明,529 是对所有用户同时出现的容量状态,所以它指向厂商侧,而不是你这一侧。

429

你被限流了

这个才是「你超了自己的速率或额度」。529 和 429 的处理方式完全不同,别用同一套逻辑。官方文档还有一条容易忽略的细节:如果 429 报的是消费上限或额度用尽,Claude Code 会直接判定失败、不做重试,这跟 529 的处理正好相反。

退避

唯一有效的客户端应对

指数退避 + 抖动。立刻重试只会加重拥塞,并让你更快撞上限流。官方文档把 529 重试的基础延迟默认值写成 500 毫秒(CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS),退避上限默认 32000 毫秒(CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS)。

多路

结构性缓解

同一任务能落到不同模型家族时,单点拥塞才不至于变成停工。代价是要接受模型差异。

529 和 429、503 有什么不同

截至 2026-10-20 的官方口径:529 表示服务端此刻整体过载,属于容量问题,通常是暂时的;官方错误文档写明这是对所有用户同时出现的容量状态,不是你的用量限额,也不计入配额。429 表示你触碰了自己的速率或额度上限,是配额问题;官方文档还写明,如果 429 报的是消费上限或额度用尽,Claude Code 会直接失败而不重试。503 一般指服务不可用或正在维护。三者都不代表你的请求写错了,但处理方式不同:529 应当退避重试,429 应当降速或提额,503 应当等待并关注服务状态页。把它们混在一个 catch 分支里,是最常见的错误处理写法。

为什么最近讨论变多

每当有新模型发布或大规模迁移发生,厂商的容量都会出现阶段性紧张,529 的讨论随之升温。这类波动通常随容量扩充而缓解,但对正在赶工的人来说,等厂商扩容不是可用的答案。2026-10 的官方状态页上有两条可核对的记录:2026-10-07 的一次消费上限事件里,部分组织被误判为已达上限而暂停,Claude API、Claude Code 等入口都出现请求被拒,官方记为已解决;2026-10-13 的一次 platform.claude.com 用量数据报错事件则写明 API 请求本身不受影响。

这两条记录讲的是消费上限与用量数据,都不是容量不足。Claude Code 也在 2026-10-08 与 2026-10-09 连出两个版本(2.1.295、2.1.296),分别补上无人值守重试的总等待上限和 529 退避上限两个可调项,最新版本是 2026-10-19 发布的 2.1.304。

排查顺序

第一步

确认状态码确实是 529 而不是 429。两者的响应体不同,日志里要分开统计。

第二步

查厂商状态页。若是大范围事件,客户端再怎么改都只是缓解。官方状态页把 Claude API(api.anthropic.com)与 Claude Code 列成两个独立的状态条目,要先看是哪一条挂了;截至 2026-10-20,页面上所有条目都显示正常。

第三步

检查自己的重试逻辑是否在放大拥塞:无抖动、无上限、失败即刻重试都属于放大。用 Claude Code 的话,从 2.1.292 版(2026-10-06)起可以用 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 把 529 重试的基础延迟调长;2.1.295 版(2026-10-08)起可以用 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 限制无人值守模式下等待 429 与 529 的总时长;2.1.296 版(2026-10-09)起可以用 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 把退避上限调长。

先别急着重试,先分清楚是哪个码

可以确认的

529 表示服务端容量拥塞、与请求内容无关,这是厂商文档中明确的语义。Claude Code 官方错误文档(2026-10-20 核对)的报错原文是 API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary.,并写明 A 529 is not your usage limit and doesn't count against your quota,即 529 不是你的用量限额、不计入配额;文档还说容量按模型分别统计,可以运行 /model 换一个模型继续,并写明 529 是对所有用户同时出现的容量状态。

同一份错误文档给出了重试变量的默认值:CLAUDE_CODE_MAX_RETRIES 默认 10(2.1.186 起上限 15),CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 默认 500 毫秒(可上调到 32000),CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 默认 32000 毫秒(可上调到 64000),CLAUDE_CODE_RETRY_WATCHDOG 设成 1 时会对 429 与 529 容量错误一直重试。

Claude Code CHANGELOG 记载:2.1.286 起默认设置下一次失败的模型调用最多发出 14 次请求;2.1.292 新增 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS;2.1.295 新增 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS;2.1.296 新增 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS。指数退避加抖动是被广泛验证的客户端应对方式。

不要当事实

错误文档对 529 只给出三条可执行建议:查官方状态页看容量公告、几分钟后重试、用 /model 换一个模型继续;文档同时写明 529 是对所有用户同时出现的容量状态,容量按模型分别统计。把 529 当成「厂商在悄悄限制重度用户」没有依据,把 529 和 429 混为一谈则会让你选错处理方式。

两种应对

只在客户端做退避

实现成本低,能显著降低失败率。但厂商侧持续拥塞时,你能做的只有等。

让任务能落到多个模型家族

单点拥塞不再等于停工。代价是要接受不同模型的习性差异,且任何一路都可能有自己的故障形态。多路是缓解而不是消除:切换机制本身也可能出问题。

正确的重试写法

要点有三条。第一,指数退避而不是固定间隔:首次等 1 秒,之后逐次翻倍。第二,加随机抖动:所有客户端同时退避同一时长,会造成同步的重试洪峰,反而延长拥塞。第三,设上限:重试次数和总等待时长都要封顶,否则一次拥塞会让你的任务队列无限堆积。另外,流式请求在中途断开时不要盲目从头重试,先判断已收到的内容是否可续。如果你用的是 Claude Code:官方文档写明它在报错之前会对瞬时失败自动重试最多 10 次、指数退避(2026-10-20 复核);2.1.286 版(GitHub Release 2026-09-30)改了重试的计数方式,官方 changelog 的原意是「一个上限覆盖整次模型调用」,默认设置下一次失败的调用最多发出 14 次请求;2.1.292 版(GitHub Release 2026-10-06)新增了环境变量 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS,用来给 529 重试的退避设置更长的基础延迟;2.1.295 版(GitHub Release 2026-10-08)新增 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS,限制无人值守模式下等待 429 与 529 的总时长;2.1.296 版(GitHub Release 2026-10-09)新增 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS,把 529 退避的上限调长。

官方错误文档现在把默认值都写明了:CLAUDE_CODE_MAX_RETRIES 默认 10(2.1.186 起上限 15),CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 默认 500 毫秒(可上调到 32000),CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 默认 32000 毫秒(可上调到 64000),CLAUDE_CODE_RETRY_WATCHDOG 设成 1 时会对 429 与 529 容量错误一直重试。

QCode 能接住什么、接不住什么

能接住的:同一把密钥可以在拥塞时切到别的模型家族继续干活,不必干等某一个模型恢复。接不住的:我们不是模型厂商,改不了厂商的服务器容量;经 QCode 的请求同样可能失败。我们能提供的是换模型家族的选择,而不是一份不出故障的承诺。

常见问题

收到 529 要改我的请求参数吗?

不用。529 与请求内容无关,改 max_tokens、换模型参数、精简 prompt 都不会让它消失。要改的是重试策略。

529 和 429 我可以用同一套重试逻辑吗?

不建议。529 应当退避后重试同一请求;429 意味着你需要降低发送速率或提高额度,盲目重试只会持续触发限流。

退避多久合适?

常见做法是首次 1 秒、逐次翻倍,叠加随机抖动,并对重试次数与总等待时长设上限。具体数值取决于你的任务能容忍多长延迟。用 Claude Code 的话(截至 2026-10-20 官方错误文档与 CHANGELOG):重试次数由 CLAUDE_CODE_MAX_RETRIES 控制,默认 10(2.1.186 起上限 15);2.1.286 起默认设置下一次失败的模型调用最多发出 14 次请求;2.1.292 起可以用 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 把 529 重试的基础延迟调长,官方文档写的默认值是 500 毫秒、可上调到 32000;2.1.295 起可以用 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 限制无人值守模式下等待 429 与 529 的总时长;2.1.296 起可以用 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 把退避上限调长,官方文档写的默认值是 32000 毫秒、可上调到 64000;把 CLAUDE_CODE_RETRY_WATCHDOG 设成 1,则 429 与 529 容量错误会一直重试。

流式请求中途 529 了怎么办?

先看已经收到的内容是否可用。能续写就续,不能续再整体重试。盲目从头重试会重复计费,也会加重拥塞。

QCode 会遇到 529 吗?

可能会。厂商侧的拥塞是客观存在的,我们无法免疫;我们能做的是让同一任务可以切到别的模型家族,而不是承诺不出错。

529 overloaded 是什么意思?我的额度没变,为什么还会报这个错?

529 Overloaded 是服务端的容量状态:官方错误文档写明,529 是对所有用户同时出现的容量满载,不是你的用量限额,也不计入配额,所以额度数字不变是正常的。容量按模型分别统计,遇到时可以运行 /model 换一个模型继续,官方给的建议是几分钟后重试,并到官方状态页查看容量公告。把它当成配额问题去提额、换参数,都不对症。多路能降低「一路挂了就停工」的概率,但每一路都有自己的故障形态,切换机制本身也可能出问题——它是缓解,不是消除。

信息来源

状态码语义以厂商官方 API 文档为准。Claude Code 的重试行为与 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS、CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS、CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 来自 Anthropic 的 Claude Code CHANGELOG(2.1.286、2.1.292、2.1.295、2.1.296 条目)、这些版本的 GitHub Release 页、Claude Code 错误文档与官方环境变量说明的重试变量表,以及官方状态页的组件与事件记录,均于 2026-10-20 抓取核对。来源只列官方文档与官方记录,不引用具体的第三方可用性百分比 —— 这类数字随时间波动,且我们没有权威的第三方测量来源。

拥塞时还有别的路可走

一把密钥覆盖多个模型家族,某一路紧张时可以立刻切换继续。

不确定从哪开始?

先试一周

小包 ¥26($30 额度,7 天)

每天都用

体验版 ¥63/月,每天 $5 额度;每 $1 额度只要 ¥0.42,中包约 ¥0.79