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 · 通用約定