錯誤碼完整參考

目錄

• 錯誤回應格式
• 嚴重程度說明
• 認證錯誤
• 方案限制錯誤
• Ticket 認證錯誤
• 工作階段錯誤
• 語音辨識錯誤
• 音訊處理錯誤
• 語者分離錯誤
• 多聲道錯誤
• 說話者錯誤
• 設定錯誤
• 錄音類型限制錯誤
• 翻譯服務錯誤
• TTS 語音合成錯誤
• 錄音錯誤
• 檔案匯入錯誤
• 儲存錯誤
• SSE 錯誤
• 廣播錯誤
• 互譯錯誤
• 摘要錯誤
• 重翻錯誤
• 語言切換錯誤
• 錄音名稱錯誤
• 通用錯誤
• 前端錯誤處理範例

錯誤回應格式

所有 API 錯誤使用統一格式：

{
  "type": "error",
  "data": {
    "error_code": "auth_invalid_api_key",
    "severity": "fatal",
    "message": "API Key 無效",
    "context": "auth",
    "request_id": "req_abc123xyz789",
    "timestamp": "2025-12-25T10:30:45.123Z",
    "details": null
  }
}

嚴重程度說明

句子級錯誤判斷規則（重要）：當錯誤訊息帶 sid 欄位時，無論 severity 為何，都應視為 sentence-level 錯誤（單句失敗），客戶端只需標記該句失敗並繼續，不應斷線。fatal + sid 的組合僅代表「該句嚴重失敗」，session 整體仍可繼續運作。

換句話說，「停止服務／要求重新連線」的處理建議僅適用於不帶 sid 的 session-level fatal 錯誤。

另外，部分不帶 sid 的 fatal 錯誤也不會關閉連線（例如 auth_quota_exceeded、plan_feature_not_allowed）；是否需要重新連線，以各錯誤碼的說明為準。

認證錯誤

方案限制錯誤

適用於使用「吃到飽方案」的 API Key（v1.9.0 新增；方案說明見 計費說明 – 吃到飽方案）。被下列錯誤擋下時，可透過 GET /api/v1/me/plan 查詢「我的方案含什麼、離上限多遠、限制何時恢復」。

plan_feature_not_allowed 的兩個發生時點（WebSocket）：

• start 被拒：方案不含請求中啟用的功能時，start 直接被拒；連線不會關閉，可調整參數後重新 start。
• 錄音中檢查發現：例如中途開啟方案沒有的功能，下一分鐘開始前檢查發現後該場錄音中止。

即時錄音的用量上限在每一分鐘開始前判斷，達到時下一分鐘不會開始、也不計入用量。同一把 API Key 同時進行多場錄音時，達到定期中斷的門檻後，每一場都會在各自的下一分鐘開始前中斷。

REST 端點回 HTTP 403 的場景：POST /api/v1/broadcasts（方案 key 建立廣播——廣播一律不含在吃到飽方案內）、POST /api/v1/auth/tasks/{taskId}/subtitle-feed-token 與 subtitle-share（方案不含浮動字幕）、POST /api/v1/imports（方案不含匯入）。

plan_daily_limit_reached（HTTP 402）出現在 POST /api/v1/auth/ticket 與匯入上傳：已達方案每日硬上限時，事前擋下新的錄音／匯入。 同一個字串也會出現在 POST /api/v1/imports/check-quota 的 data.reason（該端點為唯讀查詢，回 HTTP 200，不是錯誤）。

too_many_languages 語意擴充（v1.9.0）：details.max 除了系統上限（轉錄語言 10 種），也可能來自方案的「同時識別語言數上限」；details 帶 max 與 received。

Ticket 認證錯誤

工作階段錯誤

語音辨識錯誤

錄音被結束後重新開始：收到 stt_quota_exceeded、stt_silence_timeout、plan_feature_not_allowed、daily_limit_disconnect 等使錄音結束的錯誤後，可以在同一條連線上立即送出 start，但要等上一場處理完成（收到 status: "ended"）後才會收到 session_started，視摘要長度可能需要數秒到數十秒，請勿視為逾時。

音訊處理錯誤

語者分離錯誤

多聲道錯誤

適用於多聲道模式（recognition_mode: "multi_channel"，v1.10.0 新增；參數與聲道操作說明見 WebSocket API 參考 – 語音翻譯，計費見 計費說明）。以下皆為 WebSocket 錯誤，無對應 HTTP 狀態碼。

複用既有錯誤碼的多聲道語意：

• invalid_recognition_mode：多聲道功能未在此環境開通時，start 帶 recognition_mode: "multi_channel" 會回此錯；details 帶 field: "recognition_mode" 與 received_value。
• invalid_parameter：參數組合衝突時回傳——multi_channel 同時指定 speaker_diarization（多聲道本身即為語者分離）；type: "conversation" 搭配 multi_channel；set_channel_language 換成該路現行語言、transcription_languages 帶多於一個語言、或 transcription_languages 與 language 同時提供且不一致；channels[].speaker_name 超長或含控制字元。
• plan_feature_not_allowed（details.field: "max_stt_streams"）：start 或 add_channel 的聲道數超過吃到飽方案的路數上限；details 另帶 max 與當前路數。
• too_many_languages：add_channel／set_channel_language 引入新語言，使同時識別語言數超過平台上限（10 種）或方案上限；details 帶 max／received／language。

另有 speaker_op_not_allowed_multi_channel（REST 為 HTTP 422）：多聲道錄音的語者由聲道決定，語者操作僅開放改名；重新歸屬（reassign）與合併（merge）在錄音中（WebSocket）與錄音後（REST）皆會回此錯，見說話者錯誤。

說話者錯誤

設定錯誤

錄音類型限制錯誤

record（純錄音）為輕量純語音辨識類型：不支援翻譯與 TTS，摘要需 opt-in（帶 summary_template 或 summary_mode=custom 才生成）。以下錯誤碼在違反這些限制時於 start 階段回傳（自 v1.7.0 起）。

record_translation_not_allowed 亦會在事後對 record 錄音呼叫重翻端點（逐字稿重翻、摘要翻譯）時回傳。

翻譯服務錯誤

本表的 HTTP 欄是語意標註，不是實際回應狀態碼。 翻譯服務錯誤絕大多數以串流事件（SSE event: error／WebSocket type: error）送出， 而串流本身一律是 HTTP 200。此欄標的是「這個錯誤在語意上屬於哪一類」， 供您決定重試策略：4xx 表示需要調整輸入、5xx 與 429 表示可稍後重試。 請以 error_code 與 severity 判讀，不要依賴此欄比對實際收到的狀態碼。

translation_service_unavailable 的觸發規則：

• 累計型升級：llm_timeout / llm_provider_error / llm_rate_limit / llm_request_failed 連續失敗 5 次後升級
• 立即升級：llm_auth_failed / llm_deployment_not_found / llm_quota_exceeded 1 次就升級（設定/帳務問題）
• 不計入：llm_content_filtered（內容問題，非服務問題）
• 去重：每個 session 只通知一次，任一句翻譯成功則重置；可再次觸發
• payload：type: "error"，不帶 sid，details 含 provider、last_error_code、fail_count
• 觀眾通知：廣播模式下，所有觀眾（不限語言）也會收到此事件（透過 SSE/WS 廣播通道）

TTS 語音合成錯誤

HTTP 欄為 — 表示該錯誤碼不是以 HTTP 狀態碼回傳，而是在連線建立後，透過串流中的 error 或 tts_error 事件送出。

錄音錯誤

可用額度欄位（remaining_budget 與 budget_scope）

auth_quota_exceeded 與 stt_quota_exceeded 的 details 會帶這兩個欄位。

重要：remaining_budget 是「發出這次請求的 API Key」可動用的額度，不是終端使用者的餘額。 若您是代其他使用者呼叫本服務的整合方，請不要把這個數字直接顯示給您的終端使用者—— 它反映的是您自己那把金鑰的狀態。

注意：廣播為獨立付費：即使金鑰綁著方案，廣播仍依實際用量扣點，因此廣播場次收到這兩顆碼時 budget_scope 會是 api_key_credit、remaining_budget 是真實的可用點數。

處理狀態不符（invalid_processing_status）

此錯誤碼用於 POST /api/v1/tasks/{taskId}/force-fail、POST /api/v1/tasks/{taskId}/retry 與 DELETE /api/v1/tasks/{taskId}，當錄音狀態不符操作前提時回應。details 欄位可進一步判別觸發原因：

任務仍在處理中（task_already_processing）

POST /api/v1/tasks/{taskId}/retry 在同一筆任務仍有處理作業尚未結束時回應。與 invalid_processing_status 的差別在於：這是暫時性的——任務狀態不會被本次請求改動，等前一次處理結束後，同一個請求即可成功。

注意：任務失敗後系統會自動再試數次，這段期間 processing_status 可能已經是 failed，但重試請求仍會收到 409 —— 代表自動重試尚未結束。此時不需要做任何處置，隔幾分鐘再送出同一個請求即可。

檔案匯入錯誤

注意：上傳時若點數不足，會回傳 auth_insufficient_credit 錯誤（HTTP 402）。

HTTP 欄為 - 的錯誤碼不是以 HTTP 狀態碼回傳，而是出現在匯入失敗時的 error_code：匯入查詢 API、匯入進度 SSE 的 failed 事件，以及 import.failed Webhook。對應的 error_message 是固定的一般說明，不含內部細節；需要排查時請提供 import_id。

儲存錯誤

SSE 錯誤

廣播錯誤

HTTP 欄為 — 表示該錯誤碼不是以 HTTP 狀態碼回傳，而是在連線建立後，透過串流中的 error 或 tts_error 事件送出。

互譯錯誤

處理策略：

conversation_requires_two_languages 錯誤詳情：

此錯誤在 type: "conversation" 的 start action 中，transcription_languages 數量不為 2 時發生。

{
  "type": "error",
  "data": {
    "error_code": "conversation_requires_two_languages",
    "severity": "error",
    "message": "互譯模式需要恰好 2 個語言",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "received_count": 1,
      "expected_count": 2
    }
  }
}

conversation_languages_identical 錯誤詳情：

此錯誤在 type: "conversation" 的 start action 中，提供的兩個 transcription_languages 相同時發生。

{
  "type": "error",
  "data": {
    "error_code": "conversation_languages_identical",
    "severity": "error",
    "message": "互譯的兩個語言不可相同",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "languages": ["zh-TW", "zh-TW"]
    }
  }
}

conversation_invalid_language 錯誤詳情：

此錯誤在 switch_language 時，指定的語言不在互譯語言對中。

{
  "type": "error",
  "data": {
    "error_code": "conversation_invalid_language",
    "severity": "error",
    "message": "指定語言不在互譯語言中",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "language": "ja-JP",
      "conversation_languages": ["zh-TW", "en-US"]
    }
  }
}

摘要錯誤

重翻錯誤

語言切換錯誤

錄音名稱錯誤

通用錯誤

前端錯誤處理範例

function handleError(error) {
  const { error_code, severity, message } = error.data;

  switch (severity) {
    case 'fatal':
      // 致命錯誤：停止服務，顯示錯誤頁面
      showErrorPage(message);
      disconnectWebSocket();
      break;

    case 'error':
      // 操作失敗：顯示錯誤提示，允許重試
      showErrorToast(message);
      break;

    case 'warning':
      // 警告：顯示警告，不阻斷操作
      showWarningToast(message);
      break;
  }

  // 記錄錯誤用於除錯
  console.error(`[${error_code}] ${message}`);
}

版本：V1.24.1 最後更新：2026-10-07