OpenAI API返回429怎么排查：RPM、TPM、项目限额与指数退避检查清单
直接答案
OpenAI API出现429时，先区分请求速率、令牌速率、项目级限制与额度问题，再根据限流响应头实施排队、降并发和指数退避。
症状、差异与判断依据
直接答案
先记录 HTTP 429、响应中的错误类型与错误码、x-request-id，以及 x-ratelimit-limit-、x-ratelimit-remaining-、x-ratelimit-reset- 响应头。确认请求实际使用的组织、项目和模型，再区分是请求数还是令牌数触顶。对可重试的速率限制采用带随机抖动的指数退避，并设置最大次数、总时长和并发上限；失败请求也可能消耗限制，不要立即高频重放。若错误指向账户额度或支出限制，应检查对应项目和账单状态，而不是无限退避。
一、先保存完整但脱敏的证据
日志至少记录时间、接口、模型、HTTP 状态、错误类型、错误码、x-request-id、自己的内部 trace ID、输入令牌估算、最大输出令牌和重试次数。OpenAI 官方 API 概览建议记录请求 ID，以便定位具体请求。 不要记录 API Key、Authorization 头、用户原始敏感内容或完整文件。需要比较不同环境的密钥时，只保存安全哈希的短指纹，并确保原始密钥不进入浏览器、客户端包和日志平台。
二、读取限流响应头
官方文档列出的常见响应头包括： x-ratelimit-limit-requests 与 x-ratelimit-remaining-requests。 x-ratelimit-limit-tokens 与 x-ratelimit-remaining-tokens。 x-ratelimit-reset-requests 与 x-ratelimit-reset-tokens。 项目令牌限制适用时可能出现 x-ratelimit-limit-project-tokens、remaining 与 reset 字段。 不要假定每个接口和每次失败都一定包含完全相同的头。应用应允许字段缺失，并把错误正文、HTTP 状态和当前官方文档一起解释。
三、RPM与TPM有什么区别
RPM 是单位时间内请求数量上限，TPM 是单位时间内处理令牌的上限。大量很短请求可能先耗尽 RPM；少量超长输入、大输出预留或高并发请求可能先耗尽 TPM。只看 QPS 平均值会掩盖秒级突发和令牌大小差异。 为每个请求记录输入规模和预期输出上限，按模型与项目统计滑动窗口。若 remaining requests 充足而 remaining tokens 接近零，应优先减少上下文、控制输出上限或平滑大请求，而不是只减少 HTTP 请求数。
四、确认组织、项目和模型
同一服务可能存在开发、测试和生产多个项目。环境变量、旧配置或代理可能把请求发到错误项目，导致看似“还有额度”却持续 429。记录 API 返回的组织信息，并核对运行进程实际使用的项目上下文。 模型的限流能力和使用层级可能不同，不能把一个模型页面的数值套到所有模型。查看当前模型官方页面和平台限制信息，避免把历史截图或其他账号的限制当成生产事实。
五、限流与额度问题不要混为一谈
速率限制通常适合等待窗口恢复后重试；账户额度、支出限制或项目配置问题则需要处理账户或项目状态。两者都可能表现为 429，但恢复条件不同。 以响应中的错误类型、错误码和当前平台状态为准。不要在文章或代码中永久写死某个错误字符串，因为 API 错误对象可能增加字段；应保留未知字段，并为无法分类的 429 设置安全告警。
六、指数退避应该怎么做
第一次重试等待短时间，随后按指数增加，并加入随机抖动，避免多个工作进程在同一时刻再次发送。优先参考 reset 响应头，但仍要设置最小等待、最大等待、最大次数和总重试预算。 退避必须在统一队列或并发控制层实现。若每个线程、函数和 SDK 都独立重试，实际请求数会成倍增长。先确认官方 SDK 当前是否已经默认重试部分 429，避免应用层再包多重重试。
七、失败请求也不能无限重放
官方限流指南提醒，不成功请求仍可能计入每分钟限制。零延迟循环不仅不会提高成功率，还会占用剩余容量、扩大日志量并延迟正常请求。 对交互请求设置短重试预算并快速给出可理解状态；对离线任务使用持久队列，保存任务 ID、幂等键、下一次执行时间和累计尝试次数。超过预算进入死信或人工检查，不要永久循环。
排障步骤与验证
八、控制并发与突发
平均每分钟低于限制，不代表瞬时突发一定安全。使用令牌桶、漏桶、信号量或集中队列平滑请求。并发控制应同时考虑请求数和令牌量：一个超长请求可能占用的令牌预算远高于多个短请求。 多实例服务不能只在单机内限流。若十个实例各自认为可以发送相同上限，总和仍会超标。使用共享协调、按租户配额或网关级调度，并给关键流量保留容量。
九、减少不必要的令牌消耗
删除重复系统提示、过长历史和无关检索片段；对稳定前缀评估提示缓存；在满足质量前提下设置合理输出上限。先使用令牌计数或官方计数能力估算，再发送请求。 不要为了躲避 TPM 机械截断关键上下文，导致模型产生错误。应通过检索质量、摘要、会话压缩和任务拆分控制规模，并用固定评测集确认质量没有下降。
十、批处理与异步工作负载
不要求即时响应的任务可以评估 Batch 或其他适合离线吞吐的官方能力，但必须查看当前模型、接口与配额规则。不能假定把同步请求改名为“批处理”就自动绕过所有限制。 离线队列要做去重、幂等和 checkpoint。进程重启后从已确认状态恢复，避免把同一文章、文件或用户任务再次发送并重复计费。
十一、监控指标
按项目、模型、接口和调用方记录成功率、429 率、请求令牌、输出令牌、等待队列长度、重试次数和最终失败数。将 remaining 与 reset 头作为诊断信号，而不是长期保证值。 告警应区分短暂峰值与持续故障。单个 429 可自动退避；连续窗口仍高失败、所有调用方同时异常或额度类错误应升级处理。不要让每个失败请求单独发送告警造成通知风暴。
十二、验收清单
能保存并查询 x-request-id。 能区分请求数、令牌数、项目令牌和额度类错误。 重试带指数退避、抖动、次数和总时长上限。 多实例共享并发或吞吐控制。 SDK重试与应用重试不会叠加成风暴。 离线任务具备幂等键和checkpoint。 日志不包含API Key或用户敏感正文。 在突发、长输入和项目配置错误场景下完成回归。
十三、常见错误
看到429就立即无限重试。 只统计请求数，不统计令牌量。 把测试项目的限制误认为生产项目。 SDK和业务层同时进行多次重试。 每个实例独立限流，忽略集群总量。 将额度类问题当成短暂速率限制。 为减少令牌随意截断关键上下文而不做评测。 在日志中输出完整请求或认证头。
十五、总结
OpenAI API 429 排查的核心是确定哪个项目、哪个模型、哪一种窗口资源被耗尽。用请求 ID 和限流响应头建立证据，以共享队列平滑突发，用有预算的指数退避处理可恢复错误，并把额度问题单独分类。只有在长输入、突发和多实例场景都通过回归，才能认为修复有效。
常见问题
429等待一秒后重试一定成功吗？
不一定。不同限制的恢复时间和当前队列不同，应参考响应头并使用带抖动的指数退避，且设置最大预算。
为什么请求很少仍然触发429？
可能单次输入或输出令牌很大、多个实例同时发送、项目上下文错误，或触发的并非请求数限制。查看令牌与项目相关响应头。
可以切换API Key绕过限流吗？
不应把轮换密钥当作规避限制手段。限制可能作用于项目或组织；正确方法是控制负载、检查当前层级并按官方流程调整限制。
联系支持需要提供什么？
提供时间、接口、模型、组织或项目、错误类型、`x-request-id`、脱敏复现步骤和限流头；绝不能提供完整API Key。
官方与规范资料
OpenAI API 错误处理OpenAI 官方文档