請求識別碼與問題回報

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

進階

每筆失敗回應與 SSE error 事件都帶 request_id。把它附在問題回報，我們才能在伺服器端紀錄中精準定位這次請求的完整上下文。

request_id 是這一次 API 請求的識別碼，由伺服器在收到請求時產生，回應出來時固定為 32 字元的 hex 字串。同一筆請求只會有一個 request_id,不會跨請求重複,也不會重組或縮短。

在錯誤回應中找到 request_id

JSON 模式下任何錯誤回應都包在 error 物件中,request_id 是固定四個欄位之一。即便 message 與 details 只有通用文字,request_id 仍會帶回。

JSON 模式錯誤回應範例。request_id 即為 32 字元的 hex 字串。

json

{
  "error": {
    "code": "translation_failed",
    "message": "Translation request could not be completed.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

在 SSE error 事件中找到 request_id

SSE 串流中發生業務錯誤時,伺服器會以 error 事件取代後續事件並結束串流。事件 payload 與 JSON 模式同形,request_id 一樣是固定欄位。注意 SSE 連線一旦建立,HTTP 狀態就鎖定為 200,必須讀 event payload 才能拿到 request_id。

SSE error 事件範例。整段為 SSE 的 data 欄位內容（已格式化）。

json

data: {
  "type": "error",
  "data": {
    "code": "asr_timeout",
    "message": "Speech recognition request timed out.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

回報問題時附上 request_id

我們的伺服器端紀錄以 request_id 為查找鍵。一筆 request_id 可以對應到該次請求的完整處理紀錄。提交問題時請以以下順序附上資訊。

request_id（直接複製,請保留 32 字元完整字串）。
端點路徑與 HTTP 方法（例:POST /api/v1/translations/text）。
請求發生的時間,含時區（建議 ISO 8601,例 2026-05-04T14:23:55+08:00）。
error.code 字面值（例:translation_failed、asr_timeout）。
重現步驟或最小可重現範例。請勿在報告中貼上 API 金鑰原文,必要時請以 sk_live_••• 遮罩。

回報範本

建議的格式:「[request_id] 0af76519...80319c — POST /api/v1/translations/text — 2026-05-04T14:23:55+08:00 — error.code: translation_failed — 重現:[簡述]」。固定順序讓我們可以在 30 秒內定位該請求。

request_id 為 null 時

`request_id` 在少數異常情況下可能為 null；遇 null 請以時間戳（含時區）與端點路徑作備用回報資訊，並附上錯誤碼字面值。

為什麼用 request_id 而非帳號或 IP

帳號、API 金鑰名稱、來源 IP 在同一時段可能對應到數十甚至上千筆請求；伺服器端紀錄如果只給這些欄位,需要逐筆比對才能找到問題請求,常會抓錯或抓不到。request_id 是 1 對 1 對應的最小單位,給我們 request_id 等於直接交出書架編號,請報告時務必優先使用。