# 429：限流与配额

来源: https://platform.lyrouter.com/ai_gateway/docs/rate-errors
更新日期: 2026-10-14

429 有三种来源，按 `error.message` 区分：配额或预算已用完、API Key 因错误率过高被临时熔断、模型的所有上游凭证都已达到限额。三者的处理方式不同，单靠重试解决不了配额用完的问题。

## 先判断是哪一类

| 报错原文（`error.message`） | `error.code` | 原因 | 处理 |
| --- | --- | --- | --- |
| `rate limit exceeded on <对象> <指标>/<窗口>` | — | 安全围栏的配额策略或 Key 的预算已达上限 | 等到重置时间后再调用，或请管理员调高额度 |
| `API Key 因最近 60 秒错误率过高已临时熔断，请在 N 秒后重试。` | `api_key_circuit_open` | 这个 Key 最近的请求大量失败，被网关临时熔断 | 先修复失败原因，再按 `Retry-After` 等待 |
| `all upstream credentials for this model are rate limited` | `upstream_quota_exhausted` | 能服务这个模型的所有通道或凭证都达到了各自的限额 | 稍后重试，或换用其他模型 |

此外，上游服务商自己返回的 429 会在网关回退完所有候选后原样转发，日志「状态说明」列的来源显示为「上游」。

（截图：429 示例展示网关侧拒绝，先读具体错误再核对相应限额。）

## 配额或预算用完

报错原文的三段表示哪一条限额被用完，例如 `rate limit exceeded on apikey total_tokens/day` 表示这个 Key 当天的 Token 用量已达上限：

| 位置 | 可能的值 |
| --- | --- |
| 对象 | `apikey`（API Key）、`member`（成员）、`dept`（部门）、`ws`（工作空间） |
| 指标 | `requests`（请求数）、`total_tokens`、`prompt_tokens`、`completion_tokens`（Token 数）、`credits`（Credits） |
| 窗口 | `minute`、`minutes`（N 分钟）、`day`、`month`、`total`（累计，不会重置） |

- 错误体还带 `limit`（上限）、`used`（已用）和 `reset_at`（重置时间）。`reset_at` 比窗口实际结束晚 1～2 分钟，在它之后重试不会被提前拒绝。
- 时间窗口按北京时间对齐，`day` 在每天 0 点重置；`total` 窗口不会重置，只能由管理员调高上限。
- 用量在请求完成后才计入，所以越过上限的那次请求会正常完成，下一次才被拒绝。
- 这类 429 不带 `Retry-After` 头。

**查看剩余额度**：控制台概览页的「我的配额」卡片显示适用于你的配额、剩余量和重置时间。配置了配额时，对话、向量等经过网关选路和配额检查的调用（成功的响应和被配额拦下的 429 都算）都带 `x-aigw-quota-<指标>-limit`、`x-aigw-quota-<指标>-remaining` 和 `x-aigw-quota-<指标>-reset` 响应头，指标为 `credits`、`tokens`、`requests` 等，程序可以据此提前降速。

**调高额度**：Key 的预算由 Key 创建者在 API Key 设置中调整；成员、部门和工作空间的配额由账号管理员在安全围栏中调整，见[预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota)。

## 错误率熔断

同一个 Key 在最近 60 秒内至少有 100 次请求、且其中 90% 以上失败（HTTP 状态码 ≥ 400）时，网关会临时熔断这个 Key：

- 响应头 `Retry-After` 给出需要等待的秒数，错误体中的 `retry_after`、`blocked_until` 与之一致，到时自动恢复。
- 熔断时长逐次加长：第 1 次 30 秒、第 2 次 2 分钟、第 3 次 10 分钟、第 4 次 12 小时，**第 5 次触发即永久封禁**：此后的请求返回 403 `api_key_permanently_banned`。报错原文起初是 `该 API Key 因多次高错误率请求已被永久封禁，无法恢复，请删除后创建新的 API Key。`，封禁同步到网关后变为 `该 API Key 已被永久封禁，无法恢复，请删除后创建新的 API Key。`，两者含义相同。次数在 Key 的整个生命周期内累计，不会清零。
- 网关自己返回的 402、403、429 也计入失败。一个在余额不足或被限流后仍然不停重试的程序，很快就会把 Key 熔断。
- 被熔断的请求不写入日志。

先对照[401 / 403](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)、[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)等章节找出持续失败的原因并修复，再等待 `Retry-After` 后重试。

## 上游限额

`upstream_quota_exhausted` 表示该模型所有可用的通道或凭证都已达到各自的限额，网关在排序时就把它们移出了候选。稍后重试，或换用其他模型。如果该模型只走你的 BYOK 凭证，请账号管理员检查这些凭证在服务商处的额度和限额设置，或接入更多凭证，见 [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok)。

## 常见问题

### 429 可以自动重试吗？

**答：** 可以，但要按类型处理。熔断按 `Retry-After` 等待；配额用完要等到 `reset_at` 之后，提前重试只会继续失败并计入熔断；上游限额使用有上限的指数退避加随机抖动。不要对 429 做无间隔的自动重试。

### 减少并发后仍然返回 429，怎么办？

**答：** 并发只影响频率类限制。如果报错原文中的指标是 Token 或 Credits，说明额度已经用完，减少并发无法解决，需要等待重置或调高额度。如果是 `upstream_quota_exhausted`，说明上游凭证的限额已满，可以换用其他模型。

### 提交限流问题时，需要提供哪些信息？

**答：** 响应中不包含请求 ID。请记录调用时间、模型、API Key 的名称和完整的报错原文（含 `limit`、`used`、`reset_at`）；如果能在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中找到这次请求，再附上日志详情顶部的 Request ID。被熔断的请求不会写入日志。