Codex API 返回 429 怎么解决？按错误类型逐项排查
简答：Codex API 返回 429 时，不要先盲目重试：先读取响应体中的 error.type、error.code、message，以及 Retry-After 和 request_id。若是临时限流或 slow_down，应降低请求速率并按 Retry-After 或带随机抖动的指数退避重试；若是余额、项目消费上限、组织额度或 Codex 账号 usage limit，继续重试通常无效，应先处理对应额度。本文按 API、Codex CLI 和第三方兼容网关三个场景分流。
定义：429 是 HTTP Too Many Requests，表示请求受到速率、Token、并发、余额、消费上限或使用额度等限制，但仅凭状态码不能判断具体原因。
先试这一步：保存 429 的完整响应
先不要连续点击重试，也不要先改模型。使用你当前已经确认可用的 API 端点，把响应头、响应体和状态码保存下来；不要在命令或日志中打印完整 API Key。
API_ENDPOINT='替换为你当前文档确认的请求端点'
API_KEY='替换为环境变量中的 Key'
REQUEST_JSON='替换为你当前请求体的 JSON'
curl -i -sS "$API_ENDPOINT" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "$REQUEST_JSON"
重点记录 HTTP/1.1 429 或 HTTP/2 429、error.type、error.code、message、Retry-After、可能存在的限流响应头和 request_id。OpenAI 的错误文档明确区分了请求限流、slow_down、余额耗尽、组织消费上限、项目消费上限和组织使用额度；因此仅看“429”不足以决定处理方式。查看 OpenAI 错误码文档
| 响应中看到的线索 | 更可能的类型 | 下一步 |
|---|---|---|
Retry-After，或提示请求/Token 速率过高 | 临时限流 | 先等待指定时间，降低速率，再重试 |
slow_down | 流量增长过快 | 减小突发流量，逐步恢复并发 |
credit_balance_exhausted | 预付余额耗尽 | 检查对应 API 账单和余额 |
organization_spend_limit_exceeded 或 project_spend_limit_exceeded | 组织或项目消费上限 | 检查并调整相应消费限制，或等待重置 |
organization_usage_limit_exceeded | 组织获批使用额度达到上限 | 申请提高额度或联系平台支持 |
usage_limit_reached、resets_at 或 x-codex-* | 可能是 Codex 账号或套餐窗口 | 按 Codex 使用窗口和重置时间处理，不要直接套用 API 余额结论 |
按错误类型分流：哪些 429 可以重试
1. 请求或 Token 速率超限
如果错误内容指向请求速率、Token 速率或并发突发，先降低并发、错开任务启动时间，并减少不必要的上下文和输出 Token。官方说明指出，RPM 与 TPM 是不同限制，短时间突发也可能触发限制，即使按分钟计算的平均值看起来没有超出。查看 429 排查与限流说明
2. slow_down：增长速度过快
slow_down 不等于单纯的“每分钟请求数超限”。它表示流量增长速度过快，处理方式是降低增长斜率，保持更平稳的请求节奏，再逐步提高并发。不要用多个进程同时无限重试，因为失败请求本身也可能继续消耗每分钟限制。
3. 余额、消费上限和组织额度
如果响应明确包含 credit_balance_exhausted、organization_spend_limit_exceeded、project_spend_limit_exceeded 或 organization_usage_limit_exceeded，继续等待或重复发送请求通常不能恢复访问。应登录与 API Key 对应的组织和项目，分别检查预付余额、项目消费限制、组织消费限制和获批使用额度。OpenAI 文档特别指出，计费、消费和配额类错误不能靠重试恢复。核对错误码与处理建议
4. Codex CLI 或账号使用窗口
如果错误来自 Codex CLI、ChatGPT 账号相关后端，而不是你创建的 API 项目，凭据、计费和重置窗口可能不是同一套规则。看到 usage_limit_reached、resets_at 或 x-codex-* 时，先保存重置时间和套餐字段，再按当前客户端提示等待窗口恢复。OpenAI Codex 仓库的一条公开 issue 记录了某类 429 中限额窗口信息未被客户端完整展示的情况；这只能作为特定版本问题的线索，不能据此断言所有 Codex 用户都会遇到相同现象。查看 Codex 公开 issue
重试怎么写：优先 Retry-After，缺失时再指数退避
临时限流时，优先读取 Retry-After。若不存在或格式无效，再使用带随机抖动的指数退避，并同时限制最大重试次数和总等待时间。OpenAI 帮助文档还提醒，官方 SDK 已经会对符合条件的限流错误进行部分自动重试；如果你再套一层业务重试，需要先确认 SDK 的重试次数，避免重复等待。查看官方重试建议
下面是与具体模型和端点无关的 Python 重试骨架。它只适合确认属于临时限流的 429，不适合余额、消费上限或使用额度错误。
import random
import time
import requests
MAX_RETRIES = 4
for attempt in range(MAX_RETRIES + 1):
response = requests.post(
API_ENDPOINT,
headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
json=payload,
timeout=60,
)
if response.status_code != 429:
response.raise_for_status()
result = response.json()
break
try:
error = response.json().get("error", {})
except ValueError:
error = {}
code = error.get("code")
if code in {
"credit_balance_exhausted",
"organization_spend_limit_exceeded",
"project_spend_limit_exceeded",
"organization_usage_limit_exceeded",
"usage_limit_reached",
}:
raise RuntimeError(f"429 requires quota or billing action: {code}")
if attempt == MAX_RETRIES:
raise RuntimeError("temporary 429: retry limit reached")
retry_after = response.headers.get("Retry-After")
try:
delay = float(retry_after)
except (TypeError, ValueError):
delay = min(30, 2 ** attempt) + random.uniform(0, 1)
time.sleep(max(0, delay))
exceeded retry limit 通常表示客户端自己的重试次数已经用完，不等于服务端一定已经完成了多次有效处理。排查时要同时查看最初 429 的响应体、每次重试间隔和 SDK 日志，确认是否存在 SDK 自动重试与业务重试叠加。
仍然报 429：按 API、Codex CLI、网关三层检查
- 直接 API 调用：确认 API Key 对应的组织和项目，检查 Limits 页面中的 RPM、TPM、模型限制、项目消费限制和组织消费限制。不同组织可能有不同账单和使用层级，不能只看本机配置。
- Codex CLI：区分 API Key、账号登录凭据和客户端显示的使用窗口。若响应包含
resets_at或x-codex-*，保存这些字段；如果客户端没有显示重置时间，可暂时以原始响应体为准，并检查当前 CLI 版本的公开 issue 或更新说明。 - 第三方兼容网关：先确认 429 是网关本身返回，还是网关转发了上游响应。比较响应头、错误体结构和 request ID；如果网关返回自己的错误格式，应先查看网关的限流、并发和余额规则，再向上游服务核对。不要把某个网关的限额规则当成 OpenAI API 的统一规则。
- 请求体和上下文：减少重复系统提示、历史消息、文件内容和过大的输出上限。Responses API 与 Chat Completions 使用的输出 Token 字段不同，应以当前端点文档为准，不要机械复制其他接口的参数。
- 服务状态：如果多个项目、多个客户端在同一时间突然出现 429，且本地请求速率没有变化，查看官方状态页。状态页显示的是聚合可用性，单个用户仍可能因套餐、模型或功能不同而有差异。查看 OpenAI 状态页
不要把 429 与其他状态码混淆：401 更偏向 Key 或认证问题，403 更偏向权限、地区或访问策略，404 常见于端点或资源路径不正确，500 是服务端处理错误，503 通常表示模型暂时过载。官方错误码页给出了这些状态码的区分；排查时应先确认实际 HTTP 状态和响应体，再决定是否重试。查看状态码对照
提交支持请求前，准备哪些信息
如果降速、检查额度和等待状态恢复后仍失败，整理以下脱敏信息：发生时间和时区、请求使用的模型、HTTP 状态码、完整错误码和 message、request_id、Retry-After、是否经过网关、客户端或 SDK 版本，以及已经尝试过的重试间隔。不要提交 API Key、账号密码或完整 Authorization 请求头。OpenAI 帮助文档建议保留错误详情、请求 ID、发生时间和相关限额信息，便于支持团队定位。查看支持前信息清单
本文是围绕公开文档整理的排查指南，不是 Codex 或任何 API 服务的官方页面；具体模型、套餐、限额和客户端行为应以当前控制台、客户端提示及官方文档为准。
常见问题
Codex API 返回 429，是不是 API Key 错了？
通常不能这样判断。401 更常见于 Key 无效、过期或认证配置问题；429 需要读取 error.code 和 message，可能是请求速率、Token、余额、消费上限或使用额度问题。若经过兼容网关，还要确认 429 是网关还是上游返回。
429 要等多久再重试？
如果响应包含 Retry-After，至少等待它指定的时间；没有该响应头时，使用带随机抖动的指数退避，并设置最大重试次数和总等待时间。若错误属于余额、消费上限或 usage limit，等待重试通常不能解决。
为什么平均 RPM 没超，还是会出现 429？
限流可能同时按请求数、Token 数、模型、组织或项目执行，而且短时间突发可能在更短窗口内触发限制。减少并发、错开任务启动时间，并检查 TPM、Prompt 长度和输出 Token 上限。
Codex CLI 的 429 和 API 项目的 429 一样吗？
不能直接假设一样。Codex CLI 可能涉及账号登录凭据、客户端使用窗口或特定后端字段；API 项目则通常查看 API Key 对应组织、项目和账单。看到 usage_limit_reached、resets_at 或 x-codex-* 时，应按 Codex 客户端和账号额度路径排查。
出现 exceeded retry limit 后，继续点重试有用吗？
先不要连续重试。这个提示可能只是客户端已耗尽自身重试次数，真正原因仍要回看最初 429 的 error.code、Retry-After 和响应体。若是临时限流，降低速率后再试；若是额度类错误，应先处理余额或限制。