读懂限流响应头：从识别字段到安全重试的七步指南

遇到限流，先别增加重试次数。建议把响应头当作调度信号，而不是报错附件。在 CodeRelay Hub 这样的统一接口场景中，也不要预设所有上游都使用相同字段和时间单位。按照下面七步组织解析与调度逻辑。

一、先判断错误是否值得重试

读取状态码之后，继续检查错误类型和正文。临时速率限制与余额、账单或额度问题需要不同处理；后者不能靠等待自动解决。建议把可重试错误与需要人工处理的错误分开，避免任务持续占用队列。([developers.openai.com](https://developers.openai.com/api/docs/guides/rate-limits))

二、把请求额度与令牌额度分开

OpenAI 的 x-ratelimit-remaining-requests 表示剩余请求数，x-ratelimit-remaining-tokens 表示剩余令牌额度；对应的 limit 字段表示上限。两组数值不要混用，也不要把令牌额度理解为账户余额。([developers.openai.com](https://developers.openai.com/api/docs/guides/rate-limits?utm_source=openai))

建议为每个限制维度单独保存上限、剩余量、恢复时间和观测时间。提交任务前，同时检查请求预算与预计令牌需求，不要只看请求次数还有多少。

三、确认 reset 到底是什么时间

不要看到 reset 就按时间戳解析。OpenAI 文档中的重置字段使用持续时间，例如 1s；Anthropic 的请求重置字段则使用 RFC 3339 时间。字段名字相近，不代表值的语义相同。([developers.openai.com](https://developers.openai.com/api/docs/guides/rate-limits?utm_source=openai))

建议按提供方与字段建立明确解析规则，统一转换为内部等待时长。遇到未知格式，保留原值并记录解析失败，不要猜测单位，也不要把失败结果默认为零。

四、正确处理 Retry-After

HTTP 标准允许 Retry-After 使用等待秒数或 HTTP 日期。因此，解析器既要识别非负整数，也要识别日期；不能一律转换成整数，更不能默认数值单位是毫秒。([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html?utm_source=openai))

建议将有效提示作为最早重试边界，再添加少量随机延迟。若提示超过任务截止时间，应结束任务或转入延迟队列，而不是缩短等待时间强行重发。

五、避免客户端与应用重复重试

OpenAI 官方 SDK 已经会对符合条件的限流错误自动重试，并在存在 Retry-After 时遵循该提示。接入前应检查 SDK 配置，不要无意中叠加第二套重试循环。([help.openai.com](https://help.openai.com/en/articles/5955604-how-can-i-solv?utm_source=openai))

建议只让一层负责重试，并设置最大尝试次数与总等待预算。缺少有效服务端提示时，采用有上限的指数退避和随机抖动；预算耗尽后，明确返回失败原因。

六、让调度器管理共享预算

建议把剩余额度视为一次观测，而不是下一次请求必然成功的承诺。多进程部署时，由共享调度器预留预算，并限制在途请求；不要让每个工作进程拿着同一份剩余量独立放行。

切换路由时，也不要直接沿用旧路由的额度状态。建议先确认限制作用范围，再按实际共享关系组织预算，避免错误地合并或拆分限流状态。

七、用日志和测试验证解释是否正确

建议记录状态码、请求标识、路由、原始限流字段、解析结果和最终等待时间，同时排除密钥与敏感正文。测试至少覆盖字段缺失、日期格式、持续时间格式、额度为零和并发响应乱序。

最后检查三个问题：是否读对单位，是否等待足够，是否只重试一次调度链路。先证明解析正确，再调整吞吐量。

欢迎打开 CodeRelay Hub，创建免费工作区。