OpenAI API 429 限流错误排查：RateLimitError 与 SDK 重试机制

OpenAI API 返回 429 时，官方 SDK 抛的是 RateLimitError。这类错误有两张脸——速率超限（请求太密，等一等就好）和配额耗尽（账单/额度问题，等再久也没用）。分辨它们是排查的第一步，而分辨依据就藏在 SDK 已经解析好的字段里。

1. 先读错误对象，别只读消息文本

RateLimitError 继承自 APIStatusError，几个字段是排查的入口：

• error.status_code：429
• error.code / error.type / error.body：SDK 已把响应 JSON 解进这些字段，code/type 区分速率超限与配额问题
• error.request_id：来自 x-request-id 响应头——找官方支持定位单次请求时唯一的凭据

import openai

try:
    resp = client.responses.create(model="gpt-5.6-terra", input="hi")
except openai.RateLimitError as e:
    print(e.status_code, e.code, e.type, e.request_id)

2. SDK 已经替你重试了

openai-python 的默认行为（_constants.py / _base_client.py 源码核对）：

也就是说：偶发 429 大部分时候根本不会到你手上——SDK 已经按服务端的 Retry-After 等过并重试了。你能看到 429，说明要么重试次数耗尽，要么服务端给的等待时间超过了 SDK 的上限。

3. 排查路径

按这个顺序走：

1. 看 error.code / error.type：区分速率超限还是配额耗尽——这是两条完全不同的路
2. 记 request_id：需要官方支持时它是定位凭据
3. 速率超限：降并发、加请求间隔、自建带抖动的退避（尊重 Retry-After）、评估升档或走 Batch API
4. 配额耗尽：检查用量与账单面板——重试解决不了
5. 持续性大面积 429：先查 status.openai.com 是否有平台侧事件，别把平台抖动当成自己代码的锅

4. 客户端侧的正确姿势

如果 SDK 默认重试不够：

client = openai.OpenAI(max_retries=4)  # 提高重试预算

或自建退避循环——要点是尊重 Retry-After：服务端明确告诉你等多久时，照做比固定指数退避更准。同时给重试加随机抖动，避免雪崩式的同步重试。

5. 常见误区

• 把 429 当 bug 修：它是流量控制信号，不是异常代码路径——正确处理是退避与降载
• 无限重试：配额耗尽型 429 重试一万次也没用，还放大账单侧的压力信号
• 忽略 x-request-id：没有这个 ID，官方支持无法定位你的请求

6. 下一步

• OpenAI API 错误处理与重试：401/429/5xx 实战模式 — 完整的错误分类与重试模式
• Responses API vs Chat Completions：该迁移了吗 — 入口 API 选型