Request ID

从响应头或错误信息中保存请求追踪标识，并准备可定位的排障信息。

为什么要保存 Request ID

Request ID 用于关联一次 API 请求与平台处理记录。遇到失败、异常结果、超时或计费疑问时，保存 Request ID 可以减少传递完整请求体的需要，并帮助定位对应请求。

不同协议、接口或网关路径返回的 Header 名称可能不同。检查响应头时，请依次查找：

x-request-id: REQUEST_ID
request-id: REQUEST_ID
x-oneapi-request-id: REQUEST_ID

以实际响应为准

并非每个接口或每种响应都会返回全部 Header。保存实际存在的 Request ID 即可；部分错误响应也可能在错误正文中包含 Request ID。

使用 cURL 查看响应头

先在可信的终端环境中设置当前站点的 Base URL 和 API Key。-i 会同时输出响应头和响应体：

export AGTCLOUD_BASE_URL='https://api.agtcloud.cn/v1'
export AGTCLOUD_API_KEY='your-api-key'

curl -i "${AGTCLOUD_BASE_URL:?}/chat/completions" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGTCLOUD_API_KEY:?}" \
  --data '{"model":"MODEL_ID","messages":[{"role":"user","content":"你好"}]}'

不要把包含完整 Authorization 的终端历史或截图直接发送给他人。

使用 Python 读取

import os
import requests

base_url = os.environ["AGTCLOUD_BASE_URL"]
api_key = os.environ["AGTCLOUD_API_KEY"]

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "MODEL_ID",
        "messages": [{"role": "user", "content": "你好"}],
    },
    timeout=60,
)

request_id_headers = (
    "x-request-id",
    "request-id",
    "x-oneapi-request-id",
)
request_id = next(
    (response.headers.get(name) for name in request_id_headers if response.headers.get(name)),
    None,
)
print("request_id:", request_id)
print("status:", response.status_code)

生产代码应限制日志中的响应体长度，并对 Prompt、文件内容和用户数据脱敏。

使用 JavaScript 读取

const response = await fetch(`${process.env.AGTCLOUD_BASE_URL}/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGTCLOUD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    messages: [{ role: 'user', content: '你好' }],
  }),
});

const requestIdHeaderNames = [
  'x-request-id',
  'request-id',
  'x-oneapi-request-id',
] as const;
const requestId =
  requestIdHeaderNames
    .map((name) => response.headers.get(name))
    .find((value) => value !== null) ?? null;

console.log({ requestId, status: response.status });

此示例仅适用于服务端环境。浏览器端不得持有长期 API Key。

提交排障信息时提供什么

信息	示例	是否必需
Request ID	`REQUEST_ID`	响应中存在时提供
请求时间	`2026-08-19 14:30 +08:00`	是
Method / Path	`POST /v1/chat/completions`	是
模型 ID	脱敏后准确填写	是
HTTP Status	`429`	是
错误码和简短消息	删除敏感内容	推荐
SDK 与版本	`openai` SDK 版本	使用 SDK 时提供

不应提供完整 API Key、认证 Header、用户隐私、未脱敏文件或完整请求响应。Request ID 不是 API Key，但仍应只在必要的排障场景中提供。

没有 Request ID 怎么办

仍然保存请求时间、端点、模型、状态和错误体；
确认代理、CDN 或 SDK 没有丢弃响应头；
流式请求同时记录连接建立与断开时间；
异步任务同时保存 Task ID；
提交排障信息时说明响应头和错误正文中均未找到追踪标识。

相关页面：错误与排障 · FAQ · 通用约定