API 429 报错：限流、额度用完、API_KEY_QUOTA_EXHAUSTED 怎么解决
HTTP 429 表示请求被限制了。在 HRouter 里 429 有四种不同的来源：Key 自己的额度用完、订阅额度用完、连续填错 Key 被临时限制，以及上游暂时没有可用容量。它们的处理方式完全不同，先看错误码再动手。
错误码速查
| 错误码 / 类型 | 返回信息 | 原因 | 怎么处理 |
|---|---|---|---|
API_KEY_QUOTA_EXHAUSTED |
API key 额度已用完 | 这个 Key 设置了额度上限，已用完 | 调高或取消这个 Key 的额度限制 |
USAGE_LIMIT_EXCEEDED |
日、周或月额度超限 | 订阅类分组的周期额度用完 | 等周期重置，或换分组 |
INVALID_AUTH_RATE_LIMITED |
Too many invalid authentication attempts | 短时间内多次使用错误的 Key | 先修正 Key，稍后再试 |
rate_limit_error |
All available accounts are currently rate-limited | 可服务该模型的通道暂时都在限流 | 稍后重试，或降低并发 |
API_KEY_QUOTA_EXHAUSTED：Key 额度用完
创建 Key 时可以设置 额度限制，限制这一个 Key 最多能消费多少金额。用完之后，这个 Key 会返回 429，账户里还有余额也一样。
- 打开 API 密钥，找到这个 Key，查看额度限制和已用额度。
- 编辑 Key，调高额度；不需要限制时设为
0，0表示不设上限（不是免费调用）。 - 保存后重试，不需要重建 Key，也不用改工具配置。
这种情况和账户余额不足不同：余额不足是 403，见 余额不足。
USAGE_LIMIT_EXCEEDED：订阅额度用完
订阅类分组按日、周或月设置额度。超过后返回 429，周期重置后恢复。到 订阅 页面查看当前周期的用量和重置时间。需要立刻使用的话，可以换到按量计费的分组，见 如何选择 Key 分组。
INVALID_AUTH_RATE_LIMITED：填错 Key 被临时限制
在短时间内反复使用错误的 Key 发起请求，会被临时拦截一段时间。先别重试：
- 按 API 401 报错 找到 Key 错在哪里并修正。
- 停止自动重试的脚本，等几分钟。
- 用修正后的 Key 重新请求。
rate_limit_error：上游暂时限流
返回 “All available accounts are currently rate-limited” 说明：分组里能处理这个模型的通道都在冷却中，不是你的 Key 出了问题。
- 稍后重试：通常等待几十秒到几分钟会恢复。
- 降低并发：同时发很多请求容易触发，改成排队执行。
- 指数退避重试：失败后等 1 秒、2 秒、4 秒再试，不要立刻连续重试。
- 换一个模型：同一系列的其他模型可能有空闲容量，见 编程场景怎么选模型。
- 如果持续出现，到 服务状态 看是否有已知故障。
Codex 里看到 “exceeded retry limit, last status: 429”
Codex 会自动重试，重试多次仍失败后只显示最后一个状态码，不展示原因。真正的原因在 429 的响应内容里，用 curl 直接请求一次看错误码，再按上表处理，见 Codex 常见问题。
区分 429 和 404
如果同样是“重试没有用”的情况，注意区分：model_not_found 返回的是 404，重试永远不会成功，必须改配置，见 model_not_found。429 通常是暂时的。
一个最小验证
curl -i https://hrouter.net/v1/models \
-H "Authorization: Bearer $HROUTER_API_KEY"
返回 200，说明 Key 本身没问题；再看是额度类还是限流类问题。响应体里的错误码就是答案。