429 Rate Limit

429 Rate Limit 表示服务端因为请求过快、并发过高、额度或资源限制，暂时拒 绝继续处理请求。它不一定代表“额度已经用完”，也不一定靠重试就能恢复。排 查时要先区分短期限流、quota 不足、单次请求过重和客户端重试放大。

这页适合正在接入 OpenAI-compatible API、Codex、服务端脚本、批量任务、流 式输出或内部 AI 工具的开发者。目标是把 429 从“偶发报错”拆成可定位、可观 测、可修复的工程问题。

先把 429 排查回最小请求

如果你的 Codex、SDK、脚本或内部工具遇到 429，可以先用 OfApp.cn 的统一入口复现最小请求，再决定是降并发、缩短输入、调整重试还是检查控制台额度。具体模型、能力、额度和价格请以 OfApp.cn 控制台或官方文档为准。

查看接入说明

页面摘要

项目	说明
阅读时间	约 6 分钟
更新时间	2026-07-03
适合读者	开发者、运维、产品技术负责人、正在接入 AI API 的团队
核心收益	把 429 从“多重试几次”拆成限流、quota、请求过重、并发放大和账号状态的可验证排查路径
你会得到	429 定义、排查流程图、类型判断矩阵、最小复现、修复步骤、指数退避示例、生产系统建议、脱敏日志模板、FAQ、资料来源和相关文章
边界提醒	本文不承诺 OfApp.cn 的固定额度、速率、模型或套餐；涉及账号、额度、价格和限制时，请以 OfApp.cn 控制台或官方文档为准

429 是什么

429 是 HTTP 状态码，常用于表示请求触发了速率限制或额度限制。OpenAI 官方 错误码文档也将 429 归到 rate limit 或当前 quota 超限一类问题：前者通常是 请求发送太快，需要放慢节奏；后者通常需要检查额度、账单或使用限制。

在 OpenAI-compatible API 场景里，429 常见于这些位置：

位置	典型表现	排查重点
Web 服务	多个用户同时请求后失败	并发、队列、全局限流
批处理脚本	循环跑到一半开始失败	批次大小、重试次数、输入长度
Codex 或代码代理	多步任务中连续请求失败	工具重试、上下文过长、模型调用频率
流式输出	开始前失败或多路 stream 同时失败	并发连接数、长输出、用户等待策略
后台任务	定时任务集中触发	调度削峰、任务去重、失败回退

429 类型判断矩阵

你看到的现象	更可能是什么	先做什么	不要做什么
短时间大量请求后失败，稍等能恢复	请求速率或并发触发限流	降 QPS、加队列、错峰、有限退避	继续并发重试
错误体提到 quota、billing、credit 或 spend	额度、账单、项目或账号限制	查控制台、Key 归属、项目限制和官方文档	用代码循环重试
只有长文本、长输出或多文件任务失败	单次请求资源压力过高	拆分输入、限制输出、缓存中间结果	把所有资料一次塞入
用户点击重试后失败更频繁	客户端或前端重试放大	设置最大重试次数、熔断和按钮冷却	让用户无限点重试
定时任务整点集中失败	调度峰值过高	加随机延迟、拆批、排队执行	所有任务同一时间启动
多个业务共用同一个 Key 后互相影响	多租户共享限制	按用户、任务或租户隔离队列与配额	把所有流量混在一个通道

排查 429 时，先判断它属于“速度问题”“额度问题”还是“请求形态问题”。不同类 型的修复路径完全不同：短期限流可以有限退避，quota 或账号限制则应该停止重 试并进入控制台复核。

429 排查流程图

常见原因

原因	表现	处理方向
请求频率过快	短时间内多次失败，稍等后恢复	降低 QPS，加入队列和退避
并发过高	同时发起的请求集中失败	限制并发数，分批调度
quota 或额度不足	错误体提到 quota、billing、limit	检查控制台、账单、项目或 Key
单次请求过重	长上下文、大文件、长输出更容易失败	缩短输入，限制输出，拆分任务
自动重试失控	失败后请求量越来越大	设置最大次数、熔断和日志
定时任务集中触发	每小时或每天某个时间段失败	加随机延迟，错峰执行
多租户共用 Key	某个用户流量影响所有请求	按用户限流，拆分队列和配额

快速排查表

检查项	怎么看	结论
错误体	看 type、message、状态码和请求时间	区分限流、quota 和服务端异常
请求节奏	统计每分钟请求数和并发数	判断是否需要削峰
重试日志	看同一任务是否连续重复请求	判断是否发生重试放大
输入输出	记录输入长度、附件数量、max tokens 或输出长度	判断单次请求是否过重
Key 和项目	对照控制台可用范围	判断是否是项目或额度问题
最小请求	用 curl 发送最小请求	排除业务代码和 SDK 封装问题

最小复现

排查 429 时，不要一上来改业务代码。先用最小请求确认 Base URL、Key、模型和 当前账号状态。示例使用环境变量，避免把真实 Key 写进仓库、截图或聊天记录。

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_MODEL="以控制台可用模型为准"

curl -sS -o /tmp/ofapp-429-check.json \
  -w "http_code=%{http_code}\ntime_total=%{time_total}\n" \
  "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

如果最小请求成功，而业务请求失败，重点查并发、输入长度、重试、批处理和 SDK 调用方式。如果最小请求也持续 429，优先查看 OfApp.cn 控制台或官方文档 中的额度、可用模型、账号状态和限制说明。

脱敏日志模板

排查 429 时，日志要足够还原请求节奏，但不能泄露 Key、Cookie、用户隐私或业 务敏感数据。可以按下面的字段记录：

字段	示例	用途
request_id	req_20260703_001	关联一次请求和后续重试
time	2026-07-03T07:30:00+08:00	判断是否集中在某个时间段
endpoint	/chat/completions	判断端点是否选错或混用
model_var	OPENAI_MODEL	记录变量名，不记录未确认模型承诺
status	429	区分 429、5xx、网络中断
error_type	rate_limit 或 quota	从响应体中提取，不确定就写 unknown
input_size	约 12k 字符	判断单次请求是否过重
attempt	2/3	判断是否发生重试放大
queue_depth	18	判断是否需要削峰

不要记录真实 API Key、完整用户输入、账单信息、账号邮箱、内部 Cookie 或未脱 敏文件内容。需要把日志发给 AI 或同事排查时，只保留状态、时间、端点、错误 类型和经过概括的输入规模。

修复步骤

1. 暂停无限重试、批量任务和高并发入口，避免继续放大请求量。
2. 保存脱敏日志：状态码、响应体、时间、端点、模型变量、请求耗时、任务 ID。
3. 用最小请求复现，判断问题是否来自账号、Key、Base URL 或业务请求体。
4. 降低并发和 QPS，把批处理改成队列或分批执行。
5. 缩短输入，限制输出长度，把长文、PDF、会议记录和多文件任务拆成小块。
6. 对短期限流使用有限指数退避，并加入随机抖动。
7. 对 quota、账单、账号或项目限制，不要继续重试，转去控制台或官方文档确认。

指数退避示例

OpenAI 官方限流指南建议使用指数退避处理短期限流。生产代码里要设置最大次 数，并避免对鉴权、模型名、参数错误做盲目重试。

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function withRateLimitRetry(run, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await run();
    } catch (error) {
      const status = error.status || error.statusCode;
      const retryable = status === 429 || status >= 500;
      if (!retryable || attempt === maxAttempts) throw error;

      const jitter = Math.floor(Math.random() * 250);
      const delay = 500 * 2 ** (attempt - 1) + jitter;
      await sleep(delay);
    }
  }
}

这段只是重试外壳。更重要的是在调用前控制并发，在调用后记录失败原因。若错 误体明确指向 quota 或账号限制，应停止重试，避免浪费请求和排查时间。

生产系统建议

场景	建议
用户聊天	每个用户单独限流，前端显示“稍后再试”
批量总结	控制批次大小，失败任务进入延迟队列
Codex 或代理任务	限制并发工具调用，避免多代理共用同一 Key 无节制请求
流式输出	限制同时 stream 数，超时后让用户确认是否重试
定时任务	加随机启动延迟，避免整点集中请求
内部平台	记录任务 ID、用户 ID、状态码和脱敏错误体

常见误区

误区	风险	更稳做法
无限重试	放大故障、增加成本、触发更严重限流	最大 2 到 3 次，失败后进入人工或延迟队列
只看状态码	分不清 rate limit 和 quota	读取错误体和控制台信息
所有用户共用一个队列	高流量用户影响其他人	按用户、任务或租户分配限流
长文一次塞入	单请求资源消耗过高	分段、摘要、缓存中间结果
把真实 Key 发给 AI 排查	泄露密钥	使用脱敏日志和占位 Key

资料来源

• OpenAI API 错误码指南：用于核对 429、RateLimitError、rate limit 和 current quota 的官方说明。
• OpenAI API 限流指南：用于核对随机指数退避、限流处理和请求节奏控制建议。
• OfApp.cn 主页：用于确认 OfApp.cn 与 OpenAI、Codex、GPT Image、Claude 和 API Key 相关入口。
• OfApp.cn API 直转文档：用于确认 OfApp.cn 的 Base URL、API Key、端点和 quota 相关线索；具体额度、模型、价格和限制请以控制台或官方文档为准。
• OfApp.cn 天才游乐场：用于确认 OfApp.cn 提供面向用户的在线体验入口。

常见问题

429 一定是额度用完了吗？

不一定。429 可能是短期限流、并发过高、单次请求过重，也可能是 quota 或项 目限制。要结合错误体、请求节奏和控制台状态判断。

429 应该重试几次？

短期限流可以有限重试，例如 2 到 3 次，并使用指数退避和随机抖动。不要无限 重试，也不要对鉴权、模型名或参数错误盲目重试。

quota 错误能靠重试恢复吗？

通常不能。quota、账单、项目限制或账号状态问题需要在控制台或官方文档中确 认。继续重试只会制造更多失败日志。

Streaming 请求也会触发 429 吗？

会。流式请求仍然占用连接和生成资源。多路 stream 同时进行、输出很长或用户 反复重试时，都可能触发限制。

如何判断是代码问题还是账号限制？

用 curl 跑最小请求。如果最小请求也持续 429，优先检查账号、Key、模型可用 范围和额度；如果最小请求成功，回到业务代码查并发、重试和请求体大小。

可以把完整错误日志发给 AI 排查吗？

可以，但必须先脱敏。删除 API Key、Cookie、用户信息、内部 URL、账号邮箱、 账单信息和业务敏感字段，只保留状态码、错误类型、时间、端点和脱敏响应体。

相关文章

• API 错误排查中心：从状态码进入完整错误排查路径。
• 错误重试示例：实现有限退避重试。
• insufficient quota：排查额度和账号限制。
• 500 Server Error：处理服务端临时错误。
• curl 示例：用最小请求复现 API 问题。
• OpenAI API 流式输出示例：排查流式输出中断和缓冲问题。
• context length exceeded：减少输入长度和上下文压力。

带走什么

429 Rate Limit 的解法不是“多重试几次”，而是先分清限流、quota、并发、输入 过重和重试放大。可靠修复应该包含最小复现、限流削峰、有限退避、脱敏日志和 控制台复核。