429排查 | 限流与上游负载饱和

429 Too Many Requests 是大模型 API 里最常见的错误之一。

很多人看到它会理解成：

平台坏了。
模型挂了。
通道不可用。

其实不一定。

429 更准确的意思是：

当前请求频率、并发或上游负载已经超过限制。

在 4SAPI 里，你还可能看到类似提示：

当前分组上游负载已饱和。

这句话很关键。

它说明问题不一定是你的单个请求格式错了，而是当前分组背后的上游账号、渠道或模型并发已经吃紧。

1. 429 的四种来源

不要把所有 429 都当成一种问题。

常见来源有四类：

你的业务请求太频繁。
你的客户端失败后疯狂重试。
当前 4SAPI 分组上游负载饱和。
模型供应商对账号或模型限流。

排查时要先问：

是只有我一个项目 429？
还是同一分组很多项目都 429？
是某个模型 429？
还是所有模型都 429？

这几个问题决定处理方式。

2. 用户侧先做什么

如果你只是调用方，先做四件事：

降低并发。
停掉自动重试。
换短 Prompt 测试。
稍等一会再重试。

不要写这种逻辑：

429 以后立刻重试。
失败继续重试。
最多重试 20 次。

这会把一个小拥堵放大成重试风暴。

更稳的是：

第一次失败等待 2 秒。
第二次失败等待 5 秒。
第三次失败等待 15 秒。
仍失败就转队列或人工。

这叫退避。

不是怂。

是对上游限流的基本礼貌。

3. 429 和预算也有关系

429 看起来是限流问题。

但它常常和成本治理连在一起。

比如：

某个 Agent 进入循环。
每次失败都调用 Fable 5。
429 后还继续重试。
十分钟内打出几百次请求。

这时 429 是症状。

真正的问题是：

没有并发上限。
没有重试上限。
没有预算阈值。
没有任务级熔断。

所以 4SAPI 里最好设置：

key_group 预算。
project 预算。
task_type 并发。
高级模型调用上限。
429 后最大重试次数。

不要等账单出来才知道系统在疯狂重试。

4. 管理员排查 429 看什么

管理员不能只看一句错误。

建议看这些维度：

status_code = 429 的请求量。
按 key_group 聚合。
按 project 聚合。
按 model 聚合。
按 channel 聚合。
按 task_type 聚合。

然后判断：

是不是某个项目突然暴涨。
是不是某个模型全局 429。
是不是某个 channel 负载过高。
是不是同一 request_id 重试太多。
是不是某个 Key 被滥用。

字段建议：

request_id
project_id
key_group
model
channel_id
status_code
retry_count
latency_ms
task_type
input_tokens
cost

有了这些字段，429 就不是“感觉很拥挤”。

而是能定位到：

谁在打。
打什么模型。
打了多少次。
是不是重试造成的。

5. 队列是 429 的好朋友

如果你的任务不要求实时返回，就不要所有请求直接打模型。

比如：

批量摘要。
日报生成。
内容审核。
竞品分析。
RAG 重建索引。

这些都适合走队列。

队列的好处是：

可以限制并发。
可以按优先级处理。
可以错峰。
可以失败后延迟重试。
可以保护实时请求。

企业接入 4SAPI 时，我建议拆：

realtime-key：客服、用户实时请求。
batch-key：批处理、日报、离线任务。
fable-key：高价值审查任务。

这样批量任务打出 429，也不会拖死实时客服。

6. fallback 不是随便换模型

遇到 429，很多人会说：

那就自动换模型。

可以，但要谨慎。

fallback 要考虑：

新模型能力是否够。
输出格式是否兼容。
成本是否更高。
是否会影响业务结果。
是否需要标注降级。

比如简单分类任务，从高级模型 fallback 到低成本模型通常可行。

但合同审查、代码风险审查、重要客户回复，不一定适合自动降级。

更稳的策略是：

4SAPI 的模型路由要结合 task_type。

不要只按状态码机械切换。

7. 给 AI 的 429 排错 Prompt

你是 4SAPI 429 限流排查助手。

请根据请求日志、模型、Key 分组、项目、并发、retry_count、task_type 和错误原文，判断 429 来源：
1. 单项目请求暴涨
2. 客户端重试风暴
3. 当前分组上游负载饱和
4. 某个模型或 channel 限流
5. 高级模型被低价值任务滥用

要求：
- 不建议无限重试。
- 给短期止血和长期治理建议。
- 区分实时任务和批量任务。
- 给是否适合 fallback 的判断。

这个 Prompt 很适合让 Fable 5 分析一批日志。

低成本模型可以先做聚合：

按项目、模型、Key、task_type 汇总 429。

Fable 5 再判断治理方案。

8. 429 的短期止血

如果线上正在 429，可以先做：

暂停低优先级批量任务。
降低并发。
关闭过度重试。
把失败任务放入延迟队列。
临时切换简单任务到备用模型。
给用户返回明确的稍后重试提示。

不要做：

无脑加并发。
无脑多开 worker。
无脑无限重试。
无脑把所有任务切到更贵模型。

这些都会把问题放大。

9. 429 的长期治理

长期要做：

按项目拆 Key。
按任务拆队列。
按模型设置预算。
按 task_type 设置并发。
记录 retry_count。
设置 429 告警。
定期复盘异常调用。

4SAPI 的核心价值不是让你永远不遇到 429。

而是让你知道：

429 是谁造成的。
影响了谁。
花了多少钱。
下次怎么拦住。

10. 总结

429 不是简单的“再试一次”。

它背后可能是：

并发过高。
重试风暴。
上游负载饱和。
预算和权限没管住。
任务优先级没拆。

企业级大模型接入，要把 429 当成治理信号。

一句话：

429 不怕，怕的是你一边 429 一边疯狂重试。