API 文件

Error Codes

錯誤回應格式
嚴重程度說明
認證錯誤
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
  }
}

欄位	類型	說明
`error_code`	string	錯誤碼（程式化處理用）
`severity`	string	嚴重程度：`fatal` / `error` / `warning`
`message`	string	人類可讀的錯誤訊息
`context`	string	錯誤來源分類
`sid`	int	可選。句子級錯誤的句子編號（如該句翻譯失敗）；非句子級錯誤不帶
`request_id`	string	請求追蹤 ID
`timestamp`	string	錯誤發生時間（ISO 8601）
`details`	object	額外除錯資訊；翻譯場景常見 key：`provider`、`translation_language`、`source_lang`

嚴重程度說明

severity	說明	處理建議
`fatal`	致命錯誤	停止服務，要求重新連線
`error`	操作失敗	顯示錯誤提示，允許重試
`warning`	警告	顯示警告，不阻斷操作

句子級錯誤判斷規則（重要）：當錯誤訊息帶 sid 欄位時，無論 severity 為何，都應視為 sentence-level 錯誤（單句失敗），客戶端只需標記該句失敗並繼續，不應斷線。fatal + sid 的組合僅代表「該句嚴重失敗」，session 整體仍可繼續運作。
換句話說，「停止服務／要求重新連線」的處理建議僅適用於不帶 sid 的 session-level fatal 錯誤。

認證錯誤

錯誤碼	HTTP	severity	說明	處理建議
`auth_missing_api_key`	401	fatal	缺少 API Key	確認請求包含 API Key
`auth_invalid_api_key`	401	fatal	API Key 無效	確認 API Key 正確
`auth_invalid_key_format`	401	fatal	API Key 格式錯誤	確認 API Key 格式為 `vas_` 開頭
`auth_key_expired`	401	fatal	API Key 已過期	重新申請 API Key
`auth_key_disabled`	401	fatal	API Key 已停用	聯繫技術支援
`auth_user_disabled`	403	fatal	帳戶已停用	聯繫技術支援
`auth_budget_exceeded`	402	fatal	月度預算已超額	等待下月預算重置或調整預算
`auth_account_expired`	401	fatal	帳戶服務已到期	聯繫技術支援或續約
`auth_service_error`	500	fatal	認證服務暫時不可用	稍後重試

Ticket 認證錯誤

錯誤碼	HTTP	severity	說明	處理建議
`ticket_invalid`	401	fatal	Ticket 無效或已過期	重新取得 Ticket
`ticket_expired`	401	fatal	Ticket 已過期	重新取得 Ticket
`ticket_already_used`	401	fatal	Ticket 已被使用	每個 Ticket 僅能使用一次
`ticket_validation_failed`	401	fatal	Ticket 驗證失敗	確認 Ticket 格式正確

工作階段錯誤

錯誤碼	HTTP	severity	說明	處理建議
`session_not_found`	404	error	工作階段不存在	確認工作階段 ID 正確
`session_expired`	400	error	工作階段已過期	重新建立工作階段
`session_not_started`	400	error	尚未開始錄音	先呼叫 `start`
`session_already_paused`	400	warning	已經暫停	可忽略此錯誤
`session_not_paused`	400	warning	未暫停	可忽略此錯誤
`service_shutdown`	—	warning	服務即將關閉，請重新連線	伺服器 graceful shutdown 時廣播給所有活躍 WebSocket 客戶端；客戶端應顯示維護提示並在短暫退避後重連

語音辨識錯誤

錯誤碼	HTTP	severity	說明	處理建議
`stt_init_failed`	503	fatal	服務初始化失敗	稍後重試
`stt_start_failed`	500	fatal	無法開始語音辨識	稍後重試
`stt_auth_failed`	500	fatal	服務認證失敗	聯繫技術支援
`stt_quota_exceeded`	503	fatal	使用量已達上限	稍後重試
`stt_connection_lost`	500	fatal	連線中斷	停止服務，重新連線

音訊處理錯誤

錯誤碼	HTTP	severity	說明	處理建議
`audio_invalid_format`	400	error	音訊資料格式錯誤	確認音訊格式正確
`audio_process_failed`	500	error	音訊處理失敗	稍後重試
`audio_format_unsupported`	400	error	不支援的音訊格式	使用支援的格式
`audio_decode_failed`	500	error	音訊解碼失敗	確認音訊檔案完整性

語者分離錯誤

錯誤碼	HTTP	severity	說明	處理建議
`diarization_init_failed`	503	fatal	語者分離服務初始化失敗	稍後重試
`diarization_start_failed`	500	fatal	語者分離會話開始失敗	稍後重試
`diarization_failed`	500	error	語者分離處理失敗	稍後重試
`diarization_unavailable`	503	fatal	語者分離服務不可用	確認服務狀態
`diarization_multilang_conflict`	400	error	語者分離不支援多語言（拒絕開始）	請只提供一個來源語言，或關閉語者分離

說話者錯誤

錯誤碼	HTTP	severity	說明	處理建議
`speaker_not_found`	404	error	找不到指定的說話者	確認說話者 ID 正確
`speaker_sid_not_found`	404	error	找不到指定的句子	確認句子 ID 正確
`speaker_name_empty`	400	error	說話者名稱不能為空	提供說話者名稱
`speaker_name_duplicate`	400	error	說話者名稱已被使用	使用不同的名稱
`merge_speakers_same_id`	400	error	來源和目標語者不能相同	提供不同的語者 ID

設定錯誤

錯誤碼	HTTP	severity	說明	處理建議
`config_empty`	400	error	未提供任何設定	提供至少一項設定
`config_term_too_long`	400	error	術語超過 100 字元	縮短術語長度
`config_too_many_entries`	400	error	術語數量超過 500 個	減少術語數量
`config_too_many_dict_entries`	400	error	翻譯字典超過 50 條目	減少字典條目
`config_terminology_locked`	400	error	術語庫已鎖定（錄製中）	先停止錄音再更新

翻譯服務錯誤

錯誤碼	HTTP	severity	說明	處理建議
`llm_init_failed`	503	fatal	翻譯服務初始化失敗	稍後重試
`llm_timeout`	504	error	翻譯逾時	稍後重試
`llm_rate_limit`	429	warning	請求過於頻繁	減少請求頻率
`llm_request_failed`	500	error	翻譯請求失敗	稍後重試
`llm_provider_error`	503	error	翻譯服務暫時不可用	稍後重試
`llm_content_filtered`	400	warning	內容無法翻譯	修改輸入內容
`llm_auth_failed`	500	fatal	翻譯服務認證失敗	聯繫技術支援
`llm_deployment_not_found`	500	fatal	翻譯服務設定錯誤	聯繫技術支援
`llm_quota_exceeded`	503	fatal	翻譯使用量已達上限	稍後重試
`translation_service_unavailable`	-	error	翻譯服務連續失敗達閾值（session-level，不帶 sid）	顯示全域提示「翻譯暫不可用」，不需斷線；STT 仍會繼續運作

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	severity	說明	處理建議
`tts_init_failed`	503	fatal	TTS 服務初始化失敗	稍後重試
`tts_not_enabled`	400	warning	TTS 未啟用	確認 start 時設定 tts_enabled
`tts_invalid_language`	400	error	TTS 語言無效	確認語言在 translation_languages 中
`tts_invalid_voice`	400	error	無效的語音名稱	使用 /api/v1/tts/voices 查詢
`tts_segment_not_found`	400	warning	找不到指定的句子	確認 SID 存在
`tts_translation_not_found`	400	warning	找不到該語言的翻譯	確認該語言的翻譯存在
`tts_synthesis_failed`	500	error	TTS 合成失敗	稍後重試
`tts_voice_not_found`	404	error	找不到指定的語音	確認語音名稱是否正確
`tts_sample_generation_failed`	500	error	語音示範生成失敗	稍後重試
`tts_quota_exceeded`	503	fatal	TTS 使用量已達上限	稍後重試

錄音錯誤

錯誤碼	HTTP	severity	說明	處理建議
`recording_not_found`	404	error	找不到錄音	確認 taskId 正確
`recording_unauthorized`	403	error	無權限操作此錄音	確認任務屬於該用戶
`recording_audio_not_ready`	422	error	音檔尚未就緒	稍後重試
`recording_transcript_not_ready`	422	error	逐字稿尚未產生完成或為空	確認 `processing_status = completed` 後再匯出
`recording_not_completed`	422	error	錄音尚未完成處理；不允許在進行中執行重翻／編輯／重生摘要	等待 `processing_status = completed` 後重試
`entry_not_found`	404	error	找不到指定的句子（sid 不存在於 transcript）	確認 sid 正確
`entry_text_empty`	422	error	句子原文為空	提供非空 `original_text`
`entry_text_too_long`	422	error	句子原文超過 2000 字元上限	縮短內容後重試
`transcript_revision_conflict`	409	error	逐字稿已被其他請求修改（樂觀鎖衝突）	重新讀取 transcript 取得最新 `revision` 後重試
`invalid_processing_status`	422	error	處理狀態不符操作需求	見下方「處理狀態不符（invalid_processing_status）」說明

處理狀態不符（invalid_processing_status）

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

端點	觸發條件	`details` 帶的欄位	處理建議
`force-fail`	錄音已是終態（`completed` / `failed`）	`current_status`、`message`	已完成的任務請改用 `DELETE /api/v1/tasks/{taskId}`；已失敗的任務無需再次強制失敗
`retry`	錄音不在 `failed` 狀態	`current_status`、`message`	只有 `failed` 的任務可 retry
`retry`	音檔或逐字稿尚未上傳完成	`current_status`、`audio_status`、`transcript_status`、`message`	請確認來源檔完整；若錄音源頭已損毀請改用 `force-fail` 收尾

檔案匯入錯誤

錯誤碼	HTTP	severity	說明	處理建議
`import_not_found`	404	error	找不到匯入任務	確認 import_id 正確
`import_file_too_large`	413	error	檔案大小超過限制	壓縮檔案或分割
`import_invalid_format`	415	error	不支援的音檔格式	使用 mp3/wav/m4a 格式
`import_download_failed`	500	error	下載失敗	稍後重試
`import_conversion_failed`	500	error	轉換失敗	確認音檔完整性
`import_stt_timeout`	504	error	語音辨識逾時	稍後重試
`import_stt_failed`	500	error	語音辨識失敗	稍後重試
`import_translation_failed`	500	error	翻譯處理失敗	稍後重試
`import_summary_failed`	500	warning	摘要生成失敗	稍後重試
`import_upload_failed`	500	error	結果上傳失敗	稍後重試
`import_callback_failed`	500	warning	回報進度失敗	不影響處理，可忽略
`import_invalid_request`	500	error	請求格式錯誤	確認請求格式

注意：上傳時若月度預算已超額，會回傳 auth_budget_exceeded 錯誤（HTTP 402）。

儲存錯誤

錯誤碼	HTTP	severity	說明	處理建議
`storage_connection_failed`	503	error	儲存服務連線失敗	稍後重試
`storage_upload_failed`	500	error	上傳失敗	稍後重試
`storage_download_failed`	500	error	下載失敗	稍後重試
`storage_queue_full`	500	warning	上傳佇列已滿	稍後重試

SSE 錯誤

錯誤碼	HTTP	severity	說明	處理建議
`sse_transcript_not_found`	404	error	找不到逐字稿	錄音可能尚未處理完成
`sse_missing_target_lang`	400	error	缺少目標語言參數	提供 targetLang
`sse_unsupported_language`	400	error	不支援的目標語言	使用有效的語言代碼
`sse_translation_failed`	500	error	翻譯失敗	稍後重試
`sse_summary_not_found`	404	error	找不到摘要	該錄音沒有摘要
`sse_summary_translation_failed`	500	error	摘要翻譯失敗	稍後重試
`sse_summary_regeneration_failed`	500	error	摘要重新生成失敗	稍後重試
`sse_template_not_found`	404	error	找不到摘要模板	確認模板 slug 正確

廣播錯誤

錯誤碼	HTTP	severity	說明	處理建議
`broadcast_not_enabled`	500	error	會話未啟用廣播	確認廣播設定
`broadcast_token_invalid`	401	fatal	分享連結無效	停止服務，確認分享連結正確
`broadcast_token_revoked`	401	fatal	分享連結已撤銷	停止服務，重新建立廣播
`broadcast_token_already_used`	422	error	Token 已被其他 Session 使用	關閉其他分頁後重試
`broadcast_token_required`	400	error	廣播模式需要 broadcast_token	提供 broadcast_token 參數
`broadcast_session_not_found`	404	error	找不到廣播會話	確認廣播 Token 正確
`broadcast_session_not_started`	500	error	廣播尚未開始	等待主講者開始廣播
`broadcast_not_ready`	503	warning	即時翻譯服務尚未啟動	稍後重試
`broadcast_session_ended`	410	error	廣播會話已結束	等待主講者重新開始
`broadcast_capacity_exceeded`	503	warning	超過最大觀眾數量	等待排隊或稍後重試
`broadcast_queue_timeout`	408	error	排隊逾時	重新連線嘗試
`broadcast_viewer_kicked`	403	error	已被主講者移除	聯繫主講者
`broadcast_unauthorized`	401	error	未授權存取觀眾管理 API	確認認證資訊
`broadcast_password_required`	422	error	此直播需要密碼驗證	提供正確密碼
`broadcast_password_incorrect`	422	error	密碼錯誤	確認密碼後重試
`broadcast_not_in_standby`	500	warning	目前不在預備階段	等待主講者切換至預備階段
`broadcast_cannot_revoke`	422	error	只有 pending 狀態可以撤銷	先停止直播再撤銷
`broadcast_cannot_start`	422	error	無法開始直播	確認廣播狀態為 pending
`broadcast_already_live`	422	error	已有直播進行中	先停止當前直播
`broadcast_not_live`	422	error	目前沒有直播進行中	先開始直播
`broadcast_max_viewers_exceeded`	422	error	觀眾人數上限超過系統最大值	調低觀眾人數上限

互譯錯誤

錯誤碼	HTTP	severity	說明	處理建議
`conversation_requires_two_languages`	400	error	互譯模式需恰好兩個語言	提供恰好 2 個 `transcription_languages`
`conversation_languages_identical`	400	error	互譯的兩個語言不可相同	提供兩個不同的語言
`conversation_invalid_language`	400	error	無效的互譯語言	確認語言是 `transcription_languages` 之一
`conversation_same_language`	400	warning	已是當前語言	可忽略此警告
`conversation_speaking`	400	error	正在說話中，無法執行此操作	先呼叫 `stop_speaking` 結束說話
`conversation_not_speaking`	400	warning	目前未在說話狀態	可忽略此警告
`conversation_invalid_speaker`	400	error	無效的用戶編號	使用 1 或 2
`conversation_invalid_mode`	400	error	無效的對話模式	使用 `auto` 或 `manual`
`conversation_not_manual_mode`	400	error	此操作僅限手動模式	先切換到 manual 模式
`conversation_missing_speakers`	400	error	互譯模式必須提供 speakers 設定	在 start 時提供 `speakers` 參數
`conversation_invalid_speakers`	400	error	speakers 格式錯誤	確認提供恰好 2 個 speaker 設定
`conversation_language_change_failed`	500	error	語言變更失敗（STT 重建失敗）	稍後重試
`conversation_language_same_as_peer`	400	error	新語言與另一位用戶相同	兩位用戶語言不可相同

處理策略：

錯誤碼	是否重試	處理方式
`conversation_requires_two_languages`	❌	顯示「請提供恰好 2 個語言」
`conversation_languages_identical`	❌	顯示「兩個語言不可相同」
`conversation_invalid_language`	❌	顯示「語言無效」，使用 start 時的語言
`conversation_same_language`	❌	可忽略，已是當前語言
`conversation_speaking`	❌	顯示「請先結束說話」
`conversation_not_speaking`	❌	可忽略，未在說話中
`conversation_invalid_speaker`	❌	顯示「用戶編號無效」
`conversation_invalid_mode`	❌	顯示「無效的模式」
`conversation_not_manual_mode`	❌	顯示「請先切換到手動模式」
`conversation_missing_speakers`	❌	顯示「請提供 speakers 設定」
`conversation_invalid_speakers`	❌	顯示「speakers 格式錯誤」
`conversation_language_change_failed`	✅	稍後重試，若持續失敗請重新建立連線
`conversation_language_same_as_peer`	❌	顯示「不可與另一位用戶語言相同」

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"]
    }
  }
}

摘要錯誤

錯誤碼	HTTP	severity	說明	處理建議
`summary_text_empty`	400	error	文字內容不能為空	提供文字內容
`summary_text_too_long`	400	error	文字內容超過限制（100,000 字元）	縮短文字內容
`summary_failed`	500	error	摘要生成失敗	稍後重試
`summary_timeout`	504	error	摘要生成逾時	稍後重試
`custom_prompt_too_long`	400	error	`custom_prompt` 超過 2000 字元上限	縮短 `custom_prompt` 字元數
`custom_prompt_slug_too_long`	400	error	`custom_prompt_slug` 超過 64 字元上限	縮短 `custom_prompt_slug` 字元數
`custom_prompt_slug_invalid`	400	error	`custom_prompt_slug` 含控制字元	移除換行 / Tab / NULL 等控制字元
`template_not_found`	404	error	指定 slug 的摘要模板不存在或已停用	改用 `GET /api/v1/summary-templates` 列出可用模板

重翻錯誤

錯誤碼	HTTP	severity	說明	處理建議
`retranslate_sid_not_found`	404	error	找不到指定的句子編號	確認 SID 存在
`retranslate_session_not_active`	400	error	Session 未啟動	確認 Session 狀態
`retranslate_no_target_lang`	400	error	未提供目標語言	提供 target_lang 參數
`retranslate_no_text`	400	error	未提供要翻譯的文字	提供文字內容
`retranslate_llm_not_ready`	503	error	翻譯服務未就緒	稍後重試
`retranslate_llm_failed`	500	error	翻譯失敗	稍後重試
`retranslate_failed`	500	error	重翻失敗	稍後重試

語言切換錯誤

錯誤碼	HTTP	severity	說明	處理建議
`switch_language_no_target`	400	error	未提供目標語言	提供目標語言參數
`switch_language_in_progress`	400	warning	語言切換進行中	等待切換完成
`switch_language_same_target`	400	warning	目標語言相同	可忽略此警告
`batch_retranslate_partial_failed`	500	warning	部分句子重翻失敗	可忽略，不影響主流程
`batch_retranslate_failed`	500	warning	批次重翻單句失敗（持久化於 `transcript.translation_errors`）	失敗 sid 由 `failed_sids` 匯總回報，可後續單句重試

錄音名稱錯誤

錯誤碼	HTTP	severity	說明	處理建議
`set_name_empty`	400	error	錄音名稱不能為空	提供名稱
`set_name_too_long`	400	error	名稱超過長度限制	縮短名稱
`set_name_not_ready`	400	error	Session 未開始	先開始語音辨識

通用錯誤

錯誤碼	HTTP	severity	說明	處理建議
`invalid_json`	422	error	JSON 格式錯誤	確認 JSON 格式正確
`invalid_data`	422	error	資料格式錯誤	確認資料符合 API 規格
`validation_failed`	422	error	請求驗證失敗	確認必填參數已提供
`internal_error`	-	error	伺服器處理單一 WebSocket 訊息時 panic（已被 recover）	連線保持，不應斷線；視為該則訊息失敗，可選擇重試該操作。`details.message_type` 與 `details.action` 標示失敗的具體操作（詳見 WebSocket API: 單一訊息錯誤）
`missing_transcription_languages`	400	error	未提供語音辨識語言	提供 transcription_languages
`invalid_transcription_language`	400	error	無效的語言代碼	使用有效的 BCP 47 語言代碼
`invalid_translation_language`	400	error	無效的翻譯語言代碼	`translation_languages` 必須使用支援的 BCP 47 代碼（見 languages.md）
`too_many_languages`	400	error	語言數量超過上限	最多 2 種語言
`invalid_recording_type`	400	error	錄音類型無效	使用有效的類型
`invalid_summary_template`	400	error	摘要模板無效	確認模板識別碼
`name_too_long`	400	error	名稱太長	縮短名稱長度

前端錯誤處理範例

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.5.7 最後更新：2026-05-20

Changelog

Languages