Claude API 返回 429 怎么办？限流、支出上限与队列排查

429 不能只看状态码

普通速率限制可能涉及请求数、输入 Token、输出 Token 或突增流量；官方文档也说明，达到特定支出上限时可能返回 429。应读取错误类型、详情、请求 ID 和 retry-after，不能见到 429 就无限重试。

当前文档中，Messages 的 enforced_spend_limit_reached 表示支出上限，可能没有 retry-after，等待几秒再试不能恢复。其他自设费用限制也可能用不同状态码报告。是否提高额度属于预算决定，不能由自动重试程序偷偷改变。

定位究竟是哪一层达到限制

先查看 Console 中该组织和工作区的实际限额，再按模型与时间段检查请求、输入和输出。一分钟总量看起来不高，也可能因为短时间突发触发限制。多个服务实例应共享调度信息，不要每个进程都以为自己独享组织额度。

原创例子：上午整点一百份报告一起提交，白天零星调用正常。先把任务放入有界队列并分散启动，再测排队时长和错误变化；不是马上换账号或增开密钥。新增密钥通常也不能绕过同一组织的限制。

一个有限等待的伪代码

普通限流优先尊重服务端等待指示；没有可靠等待值时可用带随机抖动的退避，但必须有总截止时间和重试次数。下面是应用策略伪代码，不是可直接调用的 SDK；未发出真实请求。

读取状态码、错误详情和 retry-after
若为支出上限：停止，告知预算负责人
若是参数、认证或权限问题：停止并修复
若是可恢复的短期限流：
    计算服务端要求的等待时间，或带抖动的退避
    若下一次尝试会超出任务截止时间：保留任务并退出
    降低队列并发，等待后有限重试
记录请求 ID、尝试次数与最终状态，不记录密钥

长期优化与上线检查

队列满时也需要明确策略：拒绝新任务、推迟执行或让用户取消，不能无限积压。保留提交时间和截止时间，过期任务在真正发出请求前再次检查；否则服务恢复后可能集中执行已经失去价值的任务并产生费用。

对稳定背景评估提示缓存，对不要求即时返回的任务评估 Batch；它们都有自己的适用条件，不能保证消除所有限流。减少无关输入、控制任务并发并设置队列容量，比失败后全部同时重试更可控。

监控错误比例、排队时长、实际 Token、取消任务和重试次数。压测应经批准并控制预算，逐步增加负载。本文不列固定套餐次数、不声称实测吞吐，也不推荐以多账号规避限额；需要更高容量时走官方申请流程。