OpenAI API 500、503、超时和连接错误怎么排查？

官方资料（2026-10-29核对）：OpenAI API Error codes · Troubleshooting API Errors and Latency · API debugging与Request ID

先按“有没有HTTP响应”分类

5分钟排查顺序

1. 保存证据：记录UTC时间、端点、模型、Project、HTTP状态、错误类型/代码、总耗时和重试次数；隐藏API Key与敏感输入。
2. 确认是否收到响应：有500/503说明请求到达服务端；纯ConnectionError或客户端Timeout可能在上游网络阶段失败。
3. 检查OpenAI Status：查看当时是否有API事件，但状态页是聚合信息，不代表每个模型、Tier和客户都完全相同。
4. 打开Service Health：在HTTP Requests视图按Project、模型和Service tier筛选，看错误率而不是只看错误数量。
5. 检查客户端链路：核对代理、DNS、TLS、企业防火墙、容器出口、Vercel/网关最大执行时间和流式响应缓冲。
6. 用受控重试验证：少量请求、限制并发、设置总deadline；持续失败再准备支持材料。

500与503应该怎样重试

500通常是OpenAI服务器处理时的内部错误，官方建议短暂等待后重试；503的server_is_overloaded表示模型暂时过载，有Retry-After时必须优先遵守。没有有效服务器等待时间时，使用指数退避并加入随机抖动，同时限制最大尝试次数和总耗时。

async function retryServerError(run, maxAttempts = 4) {
  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"]);
      if (status !== 500 && status !== 503) throw error;
      const serverWait = Number.isFinite(retryAfter) ? retryAfter * 1000 : 0;
      const fallback = Math.min(30_000, 750 * (2 ** attempt) + Math.random() * 300);
      await new Promise(resolve => setTimeout(resolve, Math.max(serverWait, fallback)));
    }
  }
  throw new Error("server retry budget exhausted");
}

示例只演示受限重试。官方SDK可能已经自动重试连接错误、408、409、429和500以上错误；增加应用层重试前先核对当前SDK版本和max_retries，避免一次业务请求被多层重复放大。

超时不等于请求一定没执行

APITimeoutError表示客户端没有在设定时间内收到完整结果。服务器可能仍在处理，或者响应在代理、网关、Serverless平台和客户端之间被中断。对可能产生重复业务效果的任务，应使用自己的Job ID、状态表或去重逻辑；不要看到超时就无条件再次创建同一任务。

超时过短会让请求在到达或完成前被客户端取消。超时过长又会占用连接和Worker。应分别考虑连接、写入、读取和整个业务操作的deadline，并根据输出Token、推理强度、文件大小和流式响应设置基线。

连接错误优先检查网络链路

APIConnectionError通常没有有效HTTP状态。依次检查：

• DNS是否能解析api.openai.com，系统时间与根证书是否正常。
• 企业代理、VPN或防火墙是否允许HTTPS出口和证书链。
• 容器、Serverless函数和CI环境是否具备发送与接收网络流量的权限。
• 代理是否缓冲或关闭流式响应，网关是否设置了更短的idle timeout。
• 是否只有Production失败而本地成功；这种情况优先对比环境变量、网络策略和部署区域。

如果客户端持续报告连接/超时错误，而Service Health的HTTP Requests没有对应请求，官方建议优先判断请求没有到达OpenAI，问题通常位于上游网络、代理或过于激进的客户端超时。

如何记录x-request-id与客户端Request ID

正常API响应会返回x-request-id，官方SDK也会在顶层响应或错误对象中提供Request ID。生产环境应记录它、模型、Project、端点、UTC时间与耗时，但不要记录完整API Key。

如果超时或网络错误导致拿不到响应头，可以在请求中主动提供唯一的X-Client-Request-Id。官方要求该值只包含ASCII字符、最多512字符并且每次请求唯一；支持团队可用它判断请求是否到达服务端。

const traceId = crypto.randomUUID();
const response = await client.responses.create(
  { model: "YOUR_MODEL", input: "..." },
  { headers: { "X-Client-Request-Id": traceId } }
);

Service Health应该看什么

使用HTTP Requests视图而不是只看Uptime，并按模型、Project和Service tier筛选。重点看错误百分比和分钟级变化，而不是错误总数；高流量系统即使错误率很低，也可能出现较多失败请求。

延迟分析应看P50、P75、P95/P99，而非平均值。Request Time受输出长度和推理影响，TTFT受未缓存输入与推理影响，Token Velocity表示生成速度。把Service Health与同Project、同模型、同Tier的Usage输出Token结合分析。

Vercel、Serverless和代理常见陷阱

• 函数最大执行时间短于API请求时间，平台先结束函数并返回自己的504或连接中断。
• 反向代理或CDN有更短的read/idle timeout，流式响应被缓冲后看似“长时间没数据”。
• 每个实例都开启SDK重试和自定义重试，瞬间形成重试风暴。
• 客户端断开后服务器任务仍运行，再次提交导致重复工作。
• Preview与Production网络策略不同，导致本地成功、线上连接失败。

这些现象需要结合平台日志判断，不能仅凭“超时”认定OpenAI服务故障。

什么时候应该停止重试

达到最大尝试次数或总deadline后停止；取消信号、业务用户离开、账单/权限错误、无效请求都不应继续重试。持续500/503时应降低并发、保存证据并等待事件恢复；持续ConnectionError则先修复网络，不要用更多并发验证。

对于429，请使用OpenAI API速率限制指南；401/403看API鉴权排查；要核对请求和成本是否出现，则查看API Usage。

联系支持前准备什么

• 受影响的Org ID、Project ID、端点、模型与Service tier。
• 错误码、错误消息、失败比例、请求耗时和开始/结束时间（注明时区）。
• x-request-id或X-Client-Request-Id示例。
• Service Health截图或表格、受影响的P50/P95/P99与正常基线。
• 已经执行的网络、代理、重试和并发检查。

常见问题

迁移时分开观测：Responses 的语义化流式事件与 Chat Completions 的 delta 不同。先阅读 端点迁移指南，避免把消费者不兼容误判成服务端超时。

如果 200 响应仍无法解析 JSON，请先区分传输错误与输出格式问题；查看 Structured Outputs、JSON mode 与不完整输出排查。