統一回應結構

所有錯誤都包在 error 物件中，固定四個欄位：code（錯誤代碼）、message（人類可讀說明）、details（補充資訊）、request_id（本次請求識別碼）。

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "issues": [
        { "field": "text", "message": "String must contain at most 5000 character(s)" }
      ]
    },
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

HTTP 狀態碼

• 200 OK — 請求成功。
• 400 Bad Request — 參數不符規格。
• 401 Unauthorized — 金鑰缺失、無效或撤銷。
• 404 Not Found — 路徑不存在或資源不存在。
• 409 Conflict — 名稱或詞彙重複。
• 413 Payload Too Large — 音訊超過上限（JSON/Base64 路徑 raw 1 MB 回 audio_too_long；multipart 檔案 15 MB 回 file_too_large）。
• 429 Too Many Requests — RPM 或當期額度超限（rate_limited_* / quota_exceeded_*）。
• 500 Internal Server Error — 伺服器內部錯誤。
• 502 Bad Gateway — 服務處理失敗（translation_failed / asr_failed）。
• 503 Service Unavailable — 服務暫時不可用。
• 504 Gateway Timeout — 處理逾時。

通用錯誤代碼

任何端點都可能遇到：

• validation_error（400）— 請求 body 驗證失敗，details.issues 列出欄位錯誤。
• unauthorized（401）— 金鑰缺失、無效或撤銷。
• not_found（404）— 路徑不存在。
• internal_server_error（500）— 伺服器內部錯誤。
• service_unavailable（503）— 服務暫時不可用，請稍後重試。

翻譯模組錯誤代碼

• model_not_found（400）— 指定的模型代碼不存在。
• content_policy_violation（400）— 內容違反安全政策。
• dictionary_type_mismatch（400）— 字庫 ID 指向的類型與參數不符（例如把 forced_replacement 字庫指派給 vocabulary 欄位）。
• dictionary_not_found（404）— 指定的字庫不存在。
• translation_failed（502）— 翻譯服務暫時不可用。
• translation_timeout（504）— 翻譯處理逾時。

語音辨識模組錯誤代碼

• unsupported_audio_format（422）— 音訊格式無法被辨識。
• asr_audio_decode_error（422）— Base64 損壞，或內容與宣告的格式不符。
• asr_content_policy_violation（400）— 內容違反安全政策。
• audio_too_long（413）— JSON（Base64）路徑音訊超過 raw 1 MB 上限；更大檔案請走 multipart。
• file_too_large（413）— multipart 上傳檔案超過 15 MB 上限。
• asr_service_busy（503）— 辨識服務忙碌中；請退避後重試。
• asr_failed（502）— 辨識服務暫時不可用。
• asr_timeout（504）— 辨識處理逾時。

字庫模組錯誤代碼

• dictionary_not_found（404）— 指定的字庫不存在。
• term_not_found（404）— 指定的詞彙不存在。
• duplicate_name（409）— 字庫名稱重複。
• duplicate_term（409）— 詞彙重複（同字庫內）。

回報問題

回報問題時請附上 request_id，我們可從伺服器端紀錄定位本次請求的完整脈絡。每一筆錯誤回應都帶有 request_id 欄位，SSE 串流的 error 事件也帶。