OpenAI API 429 错误怎么解决
简答：OpenAI API 返回 429 时，先读取响应里的 error.type、error.code 和 Retry-After：rate_limit_error、slow_down 或临时限流通常应降低并发并延迟重试；credit_balance_exhausted、project_spend_limit_exceeded、organization_spend_limit_exceeded 等账单或额度错误，重试不会恢复，必须先处理余额或限制。本文内容按 2026-10-27 检索到的官方文档整理，具体字段和 SDK 行为仍以当前官方文档为准。
定义：OpenAI API 429 是服务拒绝当前请求的 HTTP 状态码，既可能表示临时速率限制，也可能表示余额、项目支出或组织用量上限已达到。
先看这张表：429 到底该重试还是查额度
不要把所有 429 都当成“请求太快”。先记录 HTTP 状态码、响应 JSON 中的 error.type、error.code、message，再查看响应头中的 Retry-After。下表是按当前官方文档整理的排查速查表，具体错误代码可能随接口和版本变化。
| 看到的信号 | 通常意味着什么 | 下一步 |
|---|---|---|
429，rate_limit_error，slow_down | 请求增长过快，可能尚未耗尽 RPM 或 TPM | 降低并发，遵循 Retry-After；没有该字段时使用带随机抖动的指数退避 |
429，请求数或 Token 数达到限制 | 触发适用的请求速率或 Token 速率限制 | 分散请求、减少并发、缩短输入，并检查限制页面 |
credit_balance_exhausted | 组织预付额度已耗尽 | 检查 API 账单设置并补充额度，不要循环重试 |
project_spend_limit_exceeded | 项目支出上限已达到 | 检查项目设置中的支出上限，等待重置或由管理员调整 |
organization_spend_limit_exceeded | 组织强制支出上限已达到 | 检查组织级支出设置，必要时等待重置或申请调整 |
organization_usage_limit_exceeded | 达到平台分配给组织的用量上限 | 查看限制页面并申请更高的获批用量上限 |
insufficient_quota | 较宽泛的错误类型，不能仅凭它判断具体原因 | 继续读取更具体的 error.code 和错误消息 |
官方文档指出，账单、支出和配额类错误不会因为重试而恢复；而临时限流才适合等待后重试。参见 OpenAI API 错误代码文档 和 OpenAI 429 排查说明。
按“检查什么—看到什么—下一步”排查
- 检查原始响应。不要只记录“429”。保存响应 JSON、
error.type、error.code、message、请求时间和请求 ID；同时查看是否有Retry-After。 - 看到临时限流信号。如果是
slow_down、请求速率达到限制，或响应类型明确为rate_limit_error，先暂停发送，降低并发，再按服务器建议等待。当前官方文档也保留了对较早rate_limit_exceeded响应的兼容提醒，但不要把它当成永久完整清单，必须结合当前错误正文判断。 - 看到余额或支出错误。如果是
credit_balance_exhausted、project_spend_limit_exceeded、organization_spend_limit_exceeded或organization_usage_limit_exceeded，停止自动重试，进入对应账单、项目或组织设置检查。 - 检查限制维度。RPM 是每分钟请求数，TPM 是每分钟 Token 数，两者可以分别触发。限制可能作用于组织或项目，也可能因模型而不同；检查组织限制页面和实际请求使用的组织、项目。
- 检查请求形态。如果短时间创建大量并发任务，先将并发降到较低值并通过队列平滑发送；如果输入上下文很长或输出上限设置过高，缩短提示词，并根据端点使用正确的输出 Token 参数。
官方帮助文档明确说明，即使平均每分钟请求量看起来没有超限，较短时间窗口内的突发流量仍可能触发 429；失败请求也会计入每分钟限制，因此不断重发同一请求可能让问题持续更久。
可在响应头中重点观察 Retry-After、x-ratelimit-remaining-requests、x-ratelimit-remaining-tokens、x-ratelimit-reset-requests 和 x-ratelimit-reset-tokens。这些字段是否出现以及具体含义，以当前官方接口返回为准，详见 OpenAI API 速率限制文档。
最小可运行的 Python 检查与退避示例
下面示例使用标准库直接发送 Responses API 请求，便于先观察原始 HTTP 响应。模型名从环境变量读取，不假设某个模型一定对你的项目授权；请先设置 OPENAI_API_KEY 和一个当前项目可用的 OPENAI_MODEL。
import json
import os
import random
import time
import urllib.error
import urllib.request
API_KEY = os.environ["OPENAI_API_KEY"]
MODEL = os.environ["OPENAI_MODEL"]
payload = json.dumps({
"model": MODEL,
"input": "Reply with one short sentence."
}).encode("utf-8")
retryable_codes = {"slow_down", "rate_limit_exceeded"}
non_retryable_codes = {
"credit_balance_exhausted",
"project_spend_limit_exceeded",
"organization_spend_limit_exceeded",
"organization_usage_limit_exceeded"
}
for attempt in range(5):
request = urllib.request.Request(
"https://api.openai.com/v1/responses",
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
method="POST"
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
print(response.status)
print(response.read().decode("utf-8"))
break
except urllib.error.HTTPError as error:
body = error.read().decode("utf-8", errors="replace")
try:
detail = json.loads(body).get("error", {})
except json.JSONDecodeError:
detail = {}
code = detail.get("code")
error_type = detail.get("type")
print(f"HTTP {error.code}, type={error_type}, code={code}, message={detail.get('message')}")
if code in non_retryable_codes:
print("这是余额、支出或用量限制，停止重试并检查账户设置。")
break
temporary = error.code == 429 and (code in retryable_codes or (code is None and error_type == "rate_limit_error"))
if not temporary or attempt == 4:
break
retry_after = error.headers.get("Retry-After")
try:
wait = float(retry_after) if retry_after is not None else min(60, 2 ** attempt)
except ValueError:
wait = min(60, 2 ** attempt)
time.sleep(wait + random.uniform(0, 0.5))
这段逻辑只对确认属于临时限流的分支重试，并明确排除余额、支出和组织用量错误。当前官方 SDK 也可能自动重试符合条件的 429 和 503；如果应用外层再套一层重试，应核对已安装 SDK 版本的行为，或关闭其中一层，避免请求次数和总等待时间被叠加。
降低 429 的四个实用改法
- 用队列平滑并发。不要让多个任务在同一时刻集中发起请求；先限制 worker 数，再根据实际响应逐步提高。
- 同时控制 RPM 和 TPM。只降低请求数可能仍然触发 Token 限制；长上下文、重复示例和过高输出上限都会增加 Token 压力。
- 遵循服务器等待时间。
Retry-After存在且有效时，把它作为最短等待时间，并加入少量随机延迟；缺失或无效时才使用指数退避。 - 设置重试边界。限制最大尝试次数和总耗时，并处理取消、超时和网络错误。不要无限重试，也不要把账单或配额错误放进重试分支。
Chat Completions 使用的输出上限参数与 Responses API 不同，当前官方帮助文档提示应根据端点使用对应的输出 Token 参数；发布代码前请以所调用端点的官方参考文档为准。
核验时间：2026-10-27。错误码、响应头和 SDK 自动重试行为可能随官方接口、模型和 SDK 版本变化；本文示例用于诊断思路，不能替代当前账户页面及官方文档。
常见问题
OpenAI API 429 一定是请求太快吗？
不一定。429 还可能表示预付余额耗尽、项目或组织支出上限达到，或组织用量上限达到。先看 error.code 和 message，再决定重试还是检查账单与限制。
429 rate_limit_exceeded 可以重试吗？
如果响应明确属于临时速率限制，可以有限重试；应优先遵循 Retry-After，没有有效该字段时使用带随机抖动的指数退避。若同时出现 credit_balance_exhausted、project_spend_limit_exceeded 或其他账单类代码，则不要重试。具体代码以当前官方文档和实际响应为准。
为什么降低 RPM 后仍然出现 429？
因为 RPM 和 TPM 是独立限制，长提示词或过高输出 Token 上限可能先触发 Token 限制；另外，短时间突发流量也可能触发更短窗口或 slow_down。应同时降低并发、输入长度和输出上限，并查看响应头中的剩余量与重置时间。
Retry-After 缺失时应该等待多久？
官方建议使用带随机抖动的指数退避，同时限制最大重试次数和总重试时长。不要无限重试，也不要把一次请求的超时误当成整个操作可以无限延长。
官方 SDK 已经自动重试，还需要自己写重试吗？
先确认当前安装版本和配置。官方 SDK 会对符合条件的部分 429 和 503 自动重试；如果外层再次重试，必须把两层的最大次数、等待时间和总截止时间合并计算，或关闭其中一层。账单、支出和配额错误不会因自动重试恢复。