OpenAI API 怎样读取请求 ID 进行故障定位

OpenAI API 的请求 ID 不是业务返回 JSON 里的普通字段，而是排查单次 HTTP 请求时要保留的关联线索。通常，服务端会在响应头返回 x-request-id；如果客户端主动发送 X-Client-Request-Id，还可以在超时或连接异常时保留自己生成的追踪标识。实际落地时，成功响应读取响应对象的请求 ID，HTTP 错误读取异常里的请求 ID，无法拿到响应时则依赖客户端 ID。

官方地址：https://developers.openai.com/api/reference/overview

先分清三种 ID：服务端、客户端和业务 trace

排查时最容易混淆的是“我自己的 trace ID”和“OpenAI 返回的 request ID”。业务 trace 是应用内部生成的关联键，负责把一次用户操作串起多个服务；X-Client-Request-Id 是随本次 OpenAI 请求发送的客户端标识；x-request-id 则由 OpenAI 服务端返回，用来定位它收到并处理的那次请求。三者应该放在同一条结构化日志中，但所有权和出现时机不同。

因此，日志字段可以按下面的职责设计：trace_id 关联业务链路，client_request_id 记录客户端发出的值，openai_request_id 记录响应头或 SDK 暴露的服务端值。不要把客户端 ID 当成服务端确认；也不要只保存服务端 ID，因为网络故障可能让响应头根本回不到应用。

按请求结果读取 ID：成功、异常与超时分三路

先看成功响应。OpenAI 官方 Python SDK 的顶层对象提供公开的 _request_id 属性，它来自 x-request-id 响应头。对于非成功 HTTP 状态，应该捕获 APIStatusError 并读取 request_id；这条路径比只打印异常消息更适合排障，因为消息不一定包含服务端请求标识。

import openai

client = openai.AsyncOpenAI()

async def call_model(prompt: str, trace_id: str):
    # 每次调用生成一个客户端可控的关联值；不要把密钥或业务明文放进这个值。
    client_request_id = trace_id
    try:
        response = await client.responses.create(
            model="gpt-5.5",
            input=prompt,
            extra_headers={"X-Client-Request-Id": client_request_id},
        )
        # 成功响应的 _request_id 来自服务端 x-request-id 响应头。
        print({
            "trace_id": trace_id,
            "client_request_id": client_request_id,
            "openai_request_id": response._request_id,
            "status": "ok",
        })
        return response
    except openai.APIStatusError as exc:
        # HTTP 4xx/5xx 仍可能有服务端 request_id，异常路径要单独读取。
        print({
            "trace_id": trace_id,
            "client_request_id": client_request_id,
            "openai_request_id": exc.request_id,
            "status": exc.status_code,
        })
        raise
    except openai.APIConnectionError as exc:
        # 连接失败时可能没有响应头，保留客户端 ID 供后续查找。
        print({
            "trace_id": trace_id,
            "client_request_id": client_request_id,
            "openai_request_id": None,
            "status": "connection_error",
        })
        raise

上面的示例把三路结果统一成相同字段，后续检索就不必先猜异常类型。这里的 None 不是“请求一定没有到达”，只表示当前进程没有拿到服务端响应 ID；是否到达需要把客户端 ID 和时间、接口、状态一起交给后续排查。

JavaScript 和原始 HTTP 调用怎样取响应头

如果使用官方 JavaScript/TypeScript SDK，成功响应对象可以读取 _request_id；错误对象可以读取 requestID、status 和 headers。如果直接调用 HTTP API，则读取响应头中的小写规范化键 x-request-id，并显式带上 X-Client-Request-Id。不同 HTTP 客户端对响应头键的大小写处理可能不同，记录时统一转换为自己的字段名即可。

import OpenAI from "openai";

const client = new OpenAI();

async function createResponse(input, traceId) {
  // 自有 ID 只用于关联请求，必须每次调用唯一且不包含敏感内容。
  const clientRequestId = traceId;
  try {
    const response = await client.responses.create(
      { model: "gpt-5.5", input },
      { headers: { "X-Client-Request-Id": clientRequestId } },
    );
    // 成功响应公开暴露服务端返回的 _request_id。
    console.log({ traceId, clientRequestId, openaiRequestId: response._request_id });
    return response;
  } catch (error) {
    if (error instanceof OpenAI.APIError) {
      // 错误对象同时提供 requestID 和状态信息，便于关联失败请求。
      console.error({
        traceId,
        clientRequestId,
        openaiRequestId: error.requestID ?? null,
        status: error.status,
      });
    }
    throw error;
  }
}

原始 HTTP 调用时，客户端 ID 的值由应用决定；它必须是 ASCII 且长度不超过官方限制，并且每次请求保持唯一。示例中的占位值只说明请求头位置，生产环境应换成应用生成的 trace ID：

# 用客户端 trace 关联本次请求；不要把 API Key 写进脚本或日志。
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: trace-20261026-0001" \
  -d '{"model":"gpt-5.5","input":"hello"}' \
  -i

# 重点查看响应头中的 x-request-id，并把它映射到 openai_request_id 字段。

没有 x-request-id 时，先判断是哪一层丢了证据

如果日志里没有服务端 ID，不要立即把它归因于 OpenAI API。先按三个层次检查：第一，HTTP 客户端是否把响应头丢弃；第二，SDK 是否走到了连接异常而不是状态异常；第三，请求是否在代理、超时或本地网络阶段就中断。只有收到响应，才有机会读取服务端 x-request-id；连接失败和超时可能没有任何响应头。

因此，故障日志至少要同时保存业务 trace、客户端请求 ID、接口路径、模型、发生时间、HTTP 状态（若有）、异常类型和服务端请求 ID（若有）。正文或提示词可以用哈希、长度或业务标签代替，避免把敏感内容交给日志系统。OpenAI 官方错误指南也建议持久故障提交模型、错误消息和代码、请求数据与头部、时间和时区等信息，但提交前要先做脱敏。

用一张清单判断日志是否足够定位

• 成功响应：记录 SDK 的 _request_id 或原始响应头 x-request-id。
• 4xx/5xx：记录异常的 request_id 或 requestID，同时保留状态码和错误类型。
• 连接失败/超时：记录客户端 ID，并标注服务端 ID 不可得，不要伪造一个值。
• 对外提交：只提供必要的请求标识、错误信息、时间和脱敏后的上下文。

常见问题

x-request-id 是不是 Responses API 返回 JSON 里的字段？

不是。它通常位于 HTTP 响应头；官方 SDK 再把它暴露为响应对象或异常对象上的便捷属性。

客户端 ID 和服务端 request ID 应该二选一吗？

不应该。客户端 ID 用来覆盖没有完整响应的情况，服务端 ID 用来确认服务端实际返回的请求，两者同时记录最稳妥。

请求超时后还能读取服务端 request ID 吗？

不一定。超时可能发生在响应头到达前，所以应保留每次请求主动发送的客户端 ID；如果最终收到了响应，再补写服务端 ID。