Claude API 429 怎么排查:速率限制、突增限制与月度封顶
同是 Claude 429,RPM/token 限额、流量突增和组织月度支出封顶需要不同处理。按官方错误字段、响应头和控制台逐步定位。
Claude API 返回 429 时,先保留响应状态、error.details.error_code、retry-after、限额响应头和 request-id,再决定是否重试。单看 HTTP 状态会把短期限流、流量突增和组织月度支出封顶混在一起;后者反复重试也无法恢复。
先辨认官方定义的三种情况
Anthropic 速率限制文档说明 Messages API 同时按 RPM、每分钟输入 token 和每分钟输出 token 限制,短时间突发也可能超限。普通速率限制可读取 retry-after 等待再试;anthropic-ratelimit-requests-remaining 和 anthropic-ratelimit-tokens-remaining 可帮助定位瓶颈。流量陡增时,即使未用满常规限额,也可能触发 ramp limit;Messages API 的 error.details.error_code 为 ramp_limit_exceeded。组织达到层级月度支出封顶时同样可能是 429,但字段为 enforced_spend_limit_reached,且没有 retry-after;需等额度恢复或申请提高层级。
别把自设预算限制也算成 429
同一官方文档说明,组织或工作区自行设置的支出限制达到上限时,通常返回 HTTP 400、invalid_request_error,错误信息指明预算限制与恢复时间。Claude Code 工作区另有例外,可能返回带 retry-after 的 429。排障时同时记录 HTTP 状态、错误类型和具体字段,不能只搜“429”。缓存读取 token 默认不计入输入 token 每分钟限额,写入缓存的 token 则计入;因此要用响应中的用量和当前限额核对,而不是按请求总长度估算。
从一条失败请求开始复现
- 用获授权的测试 Key 发一个已知可用模型的最小非流式请求;仅在受控环境记录状态码、错误字段、
retry-after、request-id和剩余额度响应头,删除提示词与密钥。 - 若有
retry-after,等待所示秒数,限制并发后只重试一次;若字段是ramp_limit_exceeded,把批量任务摊开并按官方建议逐步放量。 - 若是
enforced_spend_limit_reached,到 Claude Console 核查组织层级与月度支出上限;不要在网关层无限重试。若为 400 的自设支出限制,核查组织与工作区预算。 - 在中转场景,再对照本站 Key 权限、用户分组、上游账号、模型和用量记录,确认错误来自哪一层;本节是排障顺序,不代表 LondAI 当前已透传全部 Anthropic 响应头。
重试与数据边界
Claude API 错误文档说明官方 SDK 默认对临时错误做有限自动重试。客户端再加重试时要避免层层叠加造成流量峰值;请求可能已执行时还要核对结果与费用,避免重复业务动作。不要把供应商的组织配额写成本站用户配额,也不要向客服工单粘贴完整请求体或 Key。
验收时看什么
用脱敏回放分别验证“短期限流可等待恢复”“突增限制放慢后恢复”“支出封顶停止无效重试”三条路径,记录请求 ID、实际重试次数和最终状态。若在 LondAI 使用,还要核对本站接入文档、OpenAI 429 对照教程及使用记录,防止把两个供应商的错误码直接套用。