# OpenRouter 429 排查清单

> 核实日期：2026-09-08。额度/速率可能随 OpenRouter 政策调整，以官方速率限制文档为准：
> https://openrouter.ai/docs/api-reference/limits/

## 一、先看清错误码

- [ ] 状态码是 **429**（限速）还是 **402**（要钱）？
  - 402 → 退避没用，先去查账户余额 / 单 Key 额度上限，充值或调高上限。
  - 429 → 继续下面的步骤。

## 二、判断 429 来源

- [ ] 错误体里有没有 `error.metadata.provider_code`？
  - 有 → 上游 provider 容量/限速问题（换时段、换模型、配置 fallback）。
  - 没有、但带 `X-RateLimit-Limit / Remaining / Reset` → 平台免费档限额。
- [ ] 是不是流式（streaming）？
  - 是 → 限流可能在 200 已发出后才到，表现为 SSE 的 `finish_reason: "error"`，要单独处理。

## 三、对照当前免费档限额

累计购买 credits（终生） | 每分钟 (RPM) | 每日 (RPD)
--- | --- | ---
不足 10（含从未购买） | 20 | 50
至少 10 | 20 | 1000

- [ ] 当天免费请求是否接近上限（50 或 1000）？
- [ ] 是否瞬间并发很高（并发比平均速率更危险）？
- [ ] 失败的请求也计入当日配额——疯狂重试只会更快打满。

## 四、处理动作

- [ ] 尊重响应里的 `Retry-After`；没有就指数退避 + 抖动，上限 30s。
- [ ] 设最大重试次数，**不要无限重试**。
- [ ] 降低并发，用共享限流队列，别让所有 worker 同时重试。
- [ ] 换一个在架的 `:free` 模型，或在代码里配置 fallback 模型。
- [ ] 仍不行：充值 ≥10 credits 提升日限额，或对关键路径用付费变体（无平台级请求上限）。

## 五、openrouter/free 能帮什么

- 能：把请求分散到多个免费模型，降低单模型被你打满的概率。
- 不能：绕过 50/1000 每日总限额；解决 provider 容量问题；解决 402。

## 六、别做这些

- [ ] 不要拿到 429 立刻高频重发。
- [ ] 不要靠「换新 API Key」来重置限速（限速是账户/平台级，新 Key 不会增加容量）。
- [ ] 不要把全部流量压在单一免费模型上。