OpenAI SDK 超时、重试与 Request ID 排错

改超时前，先分清三类失败

客户端超时、HTTP 504 和结构化 API 错误不是一回事。先记录客户端实际收到什么，再调整重试参数。

RFC 9110 把 504 定义在网关层。OpenAI Python SDK 则把 APITimeoutError 定义为客户端异常。两者可能出现在同一次故障期间，但不能混为同一个状态。

用低成本请求验证路由

测试长时间生成前，先请求模型列表。这类短请求可以把基础路由、认证问题与生成延迟拆开。

curl -sS -D /tmp/monkey-headers.txt \
  https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer ***" \
  -o /tmp/monkey-models.json

sed -n '1,20p' /tmp/monkey-headers.txt

2026 年 8 月 3 日，未携带有效认证信息的生产探测在该路径收到结构化 HTTP 401。这只能确认公开请求到达认证层，不能证明特定 Key 或模型可用。

Python：排障时不要让自动重试掩盖次数

OpenAI Python SDK 当前官方 README 说明：默认请求超时为十分钟；连接错误、408、409、429 和大于等于 500 的响应默认自动重试两次；发生客户端超时的请求也会默认重试。排障时可先关闭重试，让一次测试对应一次 SDK 尝试。

import os
import httpx
import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MONKEYAI_API_KEY"],
    base_url="https://monkeytheme.com/v1",
    max_retries=0,
    timeout=httpx.Timeout(60.0, connect=5.0, read=45.0, write=10.0),
)

try:
    models = client.models.list()
except openai.APITimeoutError:
    print("SDK 超时：未收到完整 HTTP 响应")
except openai.APIStatusError as exc:
    print("HTTP 状态：", exc.status_code)
    print("Request ID：", exc.request_id)

如果只有某个操作需要不同参数，可用 client.with_options(timeout=..., max_retries=...)。模型发现和长时间流式请求通常不适合共用同一个读取超时。

Node.js：timeout 单位是毫秒

OpenAI Node SDK 官方 README 同样记录了十分钟默认超时和两次自动重试，覆盖的错误类别与 Python SDK 大体相同。Node 的 timeout 单位是毫秒。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MONKEYAI_API_KEY,
  baseURL: "https://monkeytheme.com/v1",
  maxRetries: 0,
  timeout: 60_000,
});

try {
  await client.models.list();
} catch (err) {
  console.error(err.status ?? "没有 HTTP 状态", err.request_id ?? "没有 request ID");
}

不要把 Python 的秒数直接填进 Node 的毫秒字段。原本计划 60 秒的测试，写成 60 后只会等待 60 毫秒。

记录证据，但不要记录密钥

建议保留时间戳、接口类型、模型 ID、耗时、HTTP 状态和 request ID。不要记录 bearer token 或完整请求体。两个官方 SDK 都会在服务端返回 x-request-id 时，把它放进成功对象的 _request_id；状态错误也会在可用时暴露 request ID。

只对安全的操作重试

SDK 默认重试适合处理短暂故障，但每次重试都会重复请求。只读的模型列表通常容易判断；写操作或会触发外部副作用的接口，必须先确认幂等行为。本文不假设所有 OpenAI 兼容接口都具备幂等性。

401、账单限额或模型名错误应直接修复原因，不应增加重试。429 若带有 Retry-After，按该响应头等待。500、503 或 504 可以使用有上限的退避，并保留完整排障证据。

资料与相关教程

• OpenAI Python SDK：重试与超时
• OpenAI Node SDK：重试与超时
• OpenAI API 错误码
• RFC 9110：504 Gateway Timeout
• 504 upstream timeout 排错
• SSE 流式输出教程

常见问题