429：限流与配额
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 会在网关回退完所有候选后原样转发，日志「状态说明」列的来源显示为「上游」。
图 1：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 设置中调整；成员、部门和工作空间的配额由账号管理员在安全围栏中调整，见预算、配额与限流。
错误率熔断
同一个 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、模型不可用等章节找出持续失败的原因并修复，再等待 Retry-After 后重试。
上游限额
upstream_quota_exhausted 表示该模型所有可用的通道或凭证都已达到各自的限额，网关在排序时就把它们移出了候选。稍后重试，或换用其他模型。如果该模型只走你的 BYOK 凭证，请账号管理员检查这些凭证在服务商处的额度和限额设置，或接入更多凭证，见 BYOK。
常见问题
429 可以自动重试吗？
答： 可以，但要按类型处理。熔断按 Retry-After 等待；配额用完要等到 reset_at 之后，提前重试只会继续失败并计入熔断；上游限额使用有上限的指数退避加随机抖动。不要对 429 做无间隔的自动重试。
减少并发后仍然返回 429，怎么办？
答： 并发只影响频率类限制。如果报错原文中的指标是 Token 或 Credits，说明额度已经用完，减少并发无法解决，需要等待重置或调高额度。如果是 upstream_quota_exhausted，说明上游凭证的限额已满，可以换用其他模型。
提交限流问题时，需要提供哪些信息？
答： 响应中不包含请求 ID。请记录调用时间、模型、API Key 的名称和完整的报错原文（含 limit、used、reset_at）；如果能在请求日志中找到这次请求，再附上日志详情顶部的 Request ID。被熔断的请求不会写入日志。