免费 API 遇到 429:配额、并发与费用排查清单

区分请求数、Token 吞吐、每日余额与上游容量,给免费 API 增加有限重试和明确的费用边界。

2026-11-03 · FreeTokenBox · 核查方法

同样是 429,有时等几十秒就能恢复,有时必须等下一次额度重置,有时则是上游模型没有容量。先分类,再决定是否重试,可以减少无效请求和任务中断。

第一步:分清限制单位

RPM/RPD 计算请求数,TPM/TPD 计算 Token 数。一个带长历史的请求可能消耗大量输入 Token,即使只发一次也会超限。音频、图片和算力服务还可能使用不同计量单位。

第二步:记录一条有用的错误

记录时间、提供方、模型 ID、HTTP 状态、错误类型和重置提示。保留响应中的 retry-after 或配额头,但移除 Authorization、Cookie、API Key 和用户原文。把多家服务串联时,记录失败来自哪一层。

Groq 文档区分组织级配额;OpenRouter 还区分平台限制与上游限流。不要因为同一个客户端返回同样的 429,就假定故障来自同一个地方。

第三步:选择对应动作

  • 分钟速率上限:降低并发、缩短上下文,等待窗口恢复。
  • 每日或每月额度耗尽:停止当前队列,显示恢复时间或请求人工决定是否改用其他方案。
  • 上游容量不足:可以有限次重试,或选择另一个已经核对价格与数据条款的模型。
  • 余额或预算不足:检查账单与预算规则。不要把重新发送当成充值,也不要在未经允许时自动切付费线路。

设计有限重试

以提供方的 Retry-After 为优先;没有提示时采用有上限的退避和随机抖动。设定最大尝试次数和整项任务的截止时间。用户取消后停止队列,避免后台继续消耗资源。

如果请求可能已经被处理,但连接在接收结果前断开,直接重试可能重复执行工具或业务动作。对于会发送消息、写入数据库等任务,先设计业务幂等,不能仅依赖模型 API 的成功状态。

上线前的一次演练

用本地模拟响应测试三种情况:短暂 429、当天额度耗尽、提供方超时。验证界面是否告诉用户可采取的动作、队列是否停止、重试是否受限。无需故意冲击真实免费服务来制造限流。

官方参考

Groq 配额与响应头、OpenRouter 错误与限制。本页的排队和重试建议是工程设计建议,实际错误语义以各平台接口文档为准。