OpenAI API 速率限制怎么办？RPM、TPM、429 与重试策略

官方参考（2026-10-28 核对）：OpenAI API Rate limits · OpenAI Help：API 429 排查 · OpenAI API Error codes

先区分：速率限制、Credits 与支出上限

同一个 429 外层状态可能对应不同原因，不能看到 “quota” 就反复充值，也不能看到 “rate limit” 就更换 API Key。错误正文和 error.code 是第一证据。

RPM、TPM 和项目/组织限额是什么

RPM 是 requests per minute，每分钟请求数；TPM 是 tokens per minute，每分钟 Token 数。官方还可能按 RPD、TPD、图片/音频用量或批处理队列限制。达到 RPM 或 TPM 中任意一个，都会先触发限制；多个模型还可能共享同一限额。

速率限制按组织和项目定义，并非单个用户的独立额度，且会随模型、使用层级和项目设置变化。不要把网上旧表格中的固定数字当作你的实际额度，应在 API Platform 的 Settings → Organization → Limits 查看当前值。

从响应头确认剩余量和等待时间

当响应提供这些字段时，记录它们而不是猜测：Retry-After 表示临时重试前至少等待的秒数；x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests 说明请求预算；对应的 tokens 字段说明 Token 预算。项目级 Token 头部可能单独出现。

Retry-After 只适用于临时速率限制或模型过载场景。余额、账单、组织用量和项目支出错误需要先处理原因，等待或重试不会自动恢复。

实操排查：5 分钟定位是哪一层

1. 保存证据：记录 UTC/本地时间、HTTP 状态、error.type、error.code、响应头、请求使用的模型和项目；遮盖 API Key。
2. 查 Limits：进入 API Platform 的组织 Limits，确认模型、RPM、TPM、项目 Token 以及当前使用层级。
3. 查突发：统计最近一分钟的并发、重试数、Prompt Token 和输出 Token 预算，检查是否多个服务共用同一项目。
4. 先降载：降低 worker 数、并发 semaphore 和单次输出预算，把大批量任务放进队列。
5. 再验证：用少量请求验证恢复；如果错误变为 Credits 或 spend limit，转到对应的账单页，不要继续盲重试。

正确的 Retry-After 与指数退避

若响应带有合法的 Retry-After，至少等待该值，再增加少量随机抖动；若缺失或无效，使用 base × 2attempt + jitter，并设置最大等待、最大尝试次数和总 deadline。失败请求可能计入每分钟限制，多个实例立即重试会把问题放大。

async function callWithBackoff(run, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try { return await run(); }
    catch (error) {
      const status = error.status ?? error.response?.status;
      const retryAfter = Number(error.response?.headers?.['retry-after']);
      const serverWait = Number.isFinite(retryAfter) ? retryAfter * 1000 : 0;
      const fallback = Math.min(30_000, 500 * (2 ** attempt) + Math.random() * 250);
      if (status !== 429 && status !== 503) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.max(serverWait, fallback)));
    }
  }
  throw new Error('retry deadline exceeded');
}

示例只演示退避逻辑，不包含 API Key。若 SDK 已自动重试，先查看当前版本的重试配置；不要再包一层无限重试，避免请求量翻倍。

生产环境如何避免瞬时 429

队列和并发控制

把请求放进有上限的队列，用共享 semaphore 控制 worker 数；不要让每个 Serverless 请求各自开启一套重试。对长任务使用后台队列或持久化 job 状态，避免客户端刷新后重复提交。

减少 Token 浪费

删除不必要的历史上下文、重复示例和过大的输出上限；Responses 使用 max_output_tokens，Chat Completions 使用 max_completion_tokens。长 Prompt 和过大的输出预算会更快耗尽 TPM。

幂等与可观测性

为业务任务生成幂等 ID，记录模型、项目、请求 ID、重试次数和最终状态，但永远不要记录完整 API Key。这样可以区分真正的新请求与重试，并定位哪个项目或用户制造突发流量。

Vercel、CI/CD 和多实例部署注意事项

在 Vercel Function、容器或 CI/CD 中，限流通常是所有实例共享的组织/项目预算。单个实例看起来不高，不代表总流量没超。集中式队列、分布式限流器或按项目拆分流量比“每台机器都重试”更可靠；同时确认 Preview 不会误打生产 API。

何时升级使用层级或联系支持

先把突发流量、Token 预算、重试和项目共享问题处理好；如果稳定流量仍长期达到当前上限，再查看 Limits 页面提供的使用层级或容量选项。提升批准月度用量、项目 spend limit 和速率限制是不同动作，需由组织或项目管理员处理。无法解决时，准备错误正文、错误码、请求 ID、发生时间和已尝试步骤，联系官方支持时不要提交 API Key。

常见问题

切换端点不是绕过限流：模型与项目限额仍需按实际响应判断；若正在改接口，先对照 Responses API 与 Chat Completions 的请求、事件和状态差异。

不要把 JSON 校验失败无上限重试成新的 429；先按 Structured Outputs 与 JSON mode 指南分类拒答、截断和 Schema 错误。