429 不一定只是“请求太快”
Claude API 返回 HTTP 429 时，先读错误类别、错误详情和响应头，再决定等待还是检查账户限制。只看到429就无限重试，既不能修复所有问题，也会让日志难以判断真正原因。
当前官方说明列出的情形包括速率限制、用量层级的月度支出上限，以及部分Claude Code工作区限制。本文聚焦直接API的诊断逻辑，不把所有平台或代理返回的429都当作同一类错误。
先保存足够的脱敏信息
记录请求时间、接口、模型、运行环境、HTTP状态和request-id。再查看错误JSON中的type、message及details中的错误码，以及Retry-After是否存在。不要把API Key或完整用户材料写进排查日志。
如果你通过第三方网关调用，还要确认429到底来自网关还是上游服务。本文讨论的官方字段只有在相应响应中实际存在时才适用，不应把不存在的字段补成猜测值。
文末的小函数只根据你传入的响应信息分类，不发起网络请求，不会充值或修改账户设置，也不会自动重复发送消息。
分支一：有明确的速率恢复信息
官方说明，触及请求或token速率限制可能返回429；若响应携带Retry-After，应等待指定秒数后再考虑重试。提早重发不能绕过仍在生效的限制。
先看是否有多处并发调用：一个网页请求、一个后台任务和几个开发终端，可能共享组织级限制。只降低某个终端的频率，未必足以降低整体压力。
实际恢复方案应包含队列、并发上限、等待时间和总重试次数。不要因为读到了一个较长的等待值，就把它截短后立即再发；可把任务交回队列，等到允许的时间再领取。
分支二：月度层级支出上限
官方文档描述了一类错误码为enforced_spend_limit_reached的429，表示组织达到用量层级对应的月度阈值。这种响应没有Retry-After，持续重试不会让额度立即恢复。
此时应检查Console中的用量、层级及恢复说明，由有权限的人判断是否需要申请更高限制。不要自动充值、升级套餐或修改组织预算，也不要把网页Pro订阅的付款记录当成这项阈值已经解除的证据。
没有Retry-After本身不足以证明一定属于该情形；还要看错误详情。文末分类函数对缺少明确线索的情况返回人工核对，而不是编造一个等待秒数。
别把所有额度错误都硬塞进429
官方说明，组织或工作区自设的某些支出限制可能返回400；Claude Code工作区又有不同情形。因此排查程序应保留实际状态码，不要把“限额相关”统一改写为429，或只通过一段英文报错文本判断。
401和403也通常先指向认证与权限，不能靠延长重试间隔修复。保留错误类型，再按当前官方文档和自己的控制台对应，是比盲目套错误码表更可靠的做法。
三种429响应的分类练习
假设同一个队列收到两次失败：A请求返回429、带Retry-After为12秒；B请求返回429、details中明确给出月度阈值错误码。队列应把A延后到允许时间，并扣减有限重试预算；B则停止自动重试，转到账户核对。
若第三次只得到不完整的429页面，不能推断它等同于A或B。先保留脱敏现场，查清来源，再决定下一步。这个例子是本站设计的模拟，不是真实账户的限流记录。
文末函数把三条路径分开，并保留“不是429”的返回值。它不是完整的生产重试器，故意没有自动调用API或更改服务配置。
恢复后怎样确认问题解决
先用一条低风险请求验证原错误是否消失，再逐步恢复队列，观察重试次数、并发和错误比例。不要一次性把积压请求全释放，重新制造尖峰。
对超时或断线要另做判断：不知道服务端是否完成时，重复发送可能造成重复处理或计费。不能因为刚修好429，就把所有未知结果一并自动重放。
本文函数已用本地构造的响应测试分类逻辑，尚未对真实账户制造限流，也没有验收任何组织的当前额度、恢复时间或实际费用。
在本地调用分类函数
文末是导出的纯函数，不是自动重试客户端。使用Node.js 22或更新的受支持版本，将代码保存为claude-api-429-classifier.mjs；直接node运行该文件不带参数不会打印结果。若只想离线练习，可新建demo.mjs，先写import {classify429} from './claude-api-429-classifier.mjs';，下一行写console.log(classify429({status:429,headers:{'retry-after':'600'}}));，保存后运行node demo.mjs。
这个人为构造的输入应得到action为defer、waitSeconds为600的分类，不会联网、等待600秒或自动再次发送请求。换成没有响应头的429时应保留人工核查，不能由分类器推断账户真实额度；实际响应还需按它自己的状态、错误详情和头部处理。
一次离线运行看清三个处理分支
把文末完整代码保存为claude-api-429-classifier.mjs，在Node.js 22或24 LTS运行：node claude-api-429-classifier.mjs --demo。
依次输出三行JSON：第一行action=defer、waitSeconds=12；第二行action=account_review；第三行action=manual_review。输入均为内置虚构响应，不会等待、联网或重发请求。
defer只说明不早于指定时间再评估，完整队列还需并发与重试预算；account_review不自动充值；manual_review不会把缺少响应头推断为月度阈值。
资料来源与核对范围
https://platform.claude.com/docs/en/api/errors
https://platform.claude.com/docs/en/api/rate-limits
本文依据本批保存的官方文档正文整理。原创练习与实际运行范围已在正文中区分；涉及账户界面、权限、价格和功能支持时，请按自己的产品与当前官方说明复核。