速率与配额

NexusKey 的限流分三层，任一层触发均返回 429 并携带 Retry-After 头。

三层限流

层	维度	说明
分组速率	分组 RPM/TPM	供给保护保险丝；全组共享，高峰时段可能叠加峰时策略
Key 速率	单 Key RPM/TPM/并发	创建 Key 时可配置；未配置则不受本层限制
用户并发	单用户并发请求数	默认 5 并发/用户（站点可调）

余额在途预留

准入时网关按 输入估算 + 输出单价 × max_tokens 计算在途预留，要求：

缓存余额 - 在途预留合计 ≥ 本次估算

• 用户首个在途请求始终放行；
• 估算失败或 Redis 不可用时 fail-open；
• 请求结束释放预留并按实际 usage 结算。

大额请求被 402 但余额看似充足？

在途预留按 max_tokens 上限估算。降低 max_tokens 或等待在途请求释放即可。

客户端退避规范

1. 读 Retry-After（秒）作为首次退避；
2. 无头时指数退避：1s → 2s → 4s（加 ±20% 抖动）；
3. 连续 429 超过阈值：降并发、切模型或联系支持提额；
4. 不要用固定间隔高频重试——会加重分组限流并污染你的成功率统计。

配额视图

Key 配置了 quota/速率限制时，GET /v1/usage 返回 quota 视图（剩余量与重置时间）；详见 计费与用量查询。