OpenAI API 接入与错误速查
OpenAI API 的基础接入、Responses API、常见错误码、限流维度、请求 ID、quota、结构化输出和密钥安全排查。
| 项目 | 应该怎么填 | 排查重点 |
|---|---|---|
| Base URL | https://api.openai.com/v1 | 直连 OpenAI API 使用这个前缀。 |
| Responses API | POST /v1/responses | 新项目优先从 Responses API 开始，支持文本、工具调用、streaming 与多模态输入。 |
| Chat Completions | POST /v1/chat/completions | 旧项目和兼容层常见；新功能优先检查 Responses API。 |
| 认证 | Authorization: Bearer ... | 401 先检查凭证、组织、项目和代理转发。 |
| 组织/项目 | OpenAI-Organization / OpenAI-Project | 多组织、多项目或 legacy credential 场景建议显式指定。 |
| 请求追踪 | x-request-id / X-Client-Request-Id | 生产环境记录请求 ID，超时或网络错误时可提供自定义 client request id。 |
| 限流响应头 | x-ratelimit-* | 记录剩余请求、剩余 token 与 reset 时间，便于退避重试。 |
| Batch | /v1/batches | 适合非实时批量任务，和普通实时请求分开评估。 |
| HTTP | 类型 / 场景 | 含义 | 先检查什么 |
|---|---|---|---|
400 | invalid_request_error | 参数、消息、工具或 JSON 结构不合法。 | 检查 endpoint、model、input/messages、工具 schema、max tokens。 |
401 | invalid_authentication | 认证失败或凭证不正确。 | 检查 Bearer 凭证、组织/项目 header、环境变量和代理。 |
403 | unsupported_country_region | 地区或访问条件不支持。 | 检查账号、地区、网络出口和组织权限。 |
404 | not_found | endpoint、模型或资源不存在。 | 检查 URL、模型名、file/batch/response id。 |
409 | conflict | 资源状态冲突或并发操作冲突。 | 重新读取资源状态后重试。 |
429 | rate_limit_exceeded | 请求数或 token 速率超限。 | 看 x-ratelimit-* 头，指数退避，降低并发。 |
429 | insufficient_quota | 额度、余额或月度上限不足。 | 检查 billing、usage limit、项目预算和组织限额。 |
500 | server_error | 服务端错误。 | 带 request id 记录，退避重试。 |
503 | service_unavailable | 服务临时不可用或高负载。 | 退避重试，必要时切换模型或延迟任务。 |
| 维度 | 形式 | 备注 |
|---|---|---|
| RPM | requests / minute | 请求数维度，短时间并发容易先触发。 |
| TPM | tokens / minute | 输入、输出和估算 token 都可能影响。 |
| RPD / TPD | daily limits | 日级限制，用量大时需要看项目和组织额度。 |
| Usage limits | monthly spend | 429 quota 类错误通常不是简单限速，而是账单或月度上限。 |
| Shared limits | model family | 部分模型族共享限额，切换同族模型未必能绕开。 |
- 社区常见问题集中在 429、quota、Responses/Chat Completions 迁移、模型名 not found、结构化输出 schema、流式响应、request id 和 API key 泄露。
- 新项目优先评估 Responses API；Chat Completions 仍常见于旧项目和兼容层。
- 429 需要先区分 rate limit 和 quota：前者通常是短时间请求/Token 过多，后者通常是余额、账单或月度上限。
- 生产环境建议记录 x-request-id；遇到超时或网络错误时，可显式传 X-Client-Request-Id 方便后续排查。
- OpenAI 限流可能按 RPM、RPD、TPM、TPD、IPM 等维度触发，并且存在组织级、项目级和模型族共享限制。
- 不要把 OpenAI API key 放进浏览器、移动端或公开仓库；前端调用应通过自己的后端或受控代理。
来源：OpenAI 官方 API Reference、Responses API、错误码和限流文档，以及社区常见排查问题整理。本站只把社区问题作为选题线索；接口、模型、限额与计费事实以官方文档和控制台为准。
这是一张 OpenAI API 接入与错误码速查表，适合排查 OpenAI API 401、403、404、429 rate limit、429 quota、500、503、Responses API 调用失败、Chat Completions 迁移、结构化输出 schema、模型名 not found、请求 ID 缺失和限流 header 处理等问题。
相关搜索场景： OpenAI API 接入 · OpenAI API 报错 · OpenAI API 429 · OpenAI rate limit · OpenAI quota exceeded · OpenAI insufficient_quota · OpenAI x-request-id · Responses API · Chat Completions · OpenAI structured outputs · OpenAI model not found · OpenAI API key leaked · OpenAI-Project header · OpenAI-Organization header
FAQ
新项目应该用 Responses API 还是 Chat Completions？
新项目优先看 Responses API；Chat Completions 仍适合旧项目、兼容层或已有迁移成本较高的系统。做迁移时不要只替换 endpoint，还要检查输入结构、工具调用、streaming 和响应解析。
OpenAI 429 rate limit 和 quota 有什么区别？
rate limit 通常表示短时间请求数或 token 超限；quota 通常表示余额、账单、月度用量或项目预算问题。社区里很多“还有余额但 429”的情况实际是 TPM/RPM 或模型族共享限制。
为什么明明还有余额还是 429？
可能是 RPM、TPM、RPD、TPD、IPM 或共享模型族限制触发，不一定是余额不足。先看 response body 和 x-ratelimit-* headers，再决定是退避重试、降并发还是调项目限额。
insufficient_quota 怎么处理？
先查 billing、usage limit、项目预算、组织额度和付款状态。单纯重试通常没有用；如果是新充值或刚改限额，账单状态同步也可能有延迟。
x-request-id 有什么用？
它是 OpenAI 为每次请求生成的排查 ID。生产环境建议记录到错误日志和用户诊断信息里；报障、查 500/503、定位 streaming 中断时都比贴完整 prompt 更安全。
OpenAI-Organization 和 OpenAI-Project 必须传吗？
不是所有场景都必须；但多组织、多项目或 legacy credential 场景建议显式传，避免请求落到错误组织或项目，导致权限、额度或账单看起来“不一致”。
为什么 model_not_found 或 404？
常见原因是模型名写旧、项目没有该模型权限、endpoint 用错，或者把 Responses API 和 Chat Completions 的模型/参数混用。先用官方模型页和项目权限核对。
结构化输出为什么 400？
常见原因是 JSON Schema 不被支持、required 字段不完整、additionalProperties 设置不符合要求，或把工具 schema 和 response_format 混在一起。先用最小 schema 验证，再逐步加字段。
流式响应为什么中途断了？
先区分服务端错误、代理超时、浏览器/边缘函数超时和客户端没有消费完 SSE。长输出要记录 request id，必要时降低输出长度或改后端流式转发。
API key 泄露或被提交到 GitHub 怎么办？
立刻撤销旧 key，创建新 key，检查 usage 和 billing，轮换部署环境变量，并排查日志、前端包和移动端是否还包含旧 key。不要只删除 Git 历史里的 key。