Error Codes

Table of Contents

• Error Response Format
• Severity Levels
• Authentication Errors
• Ticket Authentication Errors
• Session Errors
• Speech Recognition Errors
• Audio Processing Errors
• Speaker Diarization Errors
• Speaker Errors
• Configuration Errors
• Translation Service Errors
• TTS Synthesis Errors
• Recording Errors
• File Import Errors
• Storage Errors
• SSE Errors
• Broadcast Errors
• Conversation Errors
• Summary Errors
• Retranslation Errors
• Language Switch Errors
• Recording Name Errors
• General Errors
• Frontend Error Handling Example

Error Response Format

All API errors use a unified format:

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

Severity Levels

Sentence-level error rule (important): When an error message includes the sid field, regardless of the severity, it should be treated as a sentence-level error (a single sentence failed). The client only needs to mark that sentence as failed and continue; it should not disconnect. A fatal + sid combination only means "this sentence failed severely"; the session as a whole can still continue operating.

In other words, the "stop the service / require reconnection" recommendation applies only to session-level fatal errors that do not include sid.

Authentication Errors

Ticket Authentication Errors

Session Errors

Speech Recognition Errors

Audio Processing Errors

Speaker Diarization Errors

Speaker Errors

Configuration Errors

Translation Service Errors

translation_service_unavailable trigger rules (backend behavior):

• Cumulative escalation: escalates after llm_timeout / llm_provider_error / llm_rate_limit / llm_request_failed fail 5 times consecutively
• Immediate escalation: llm_auth_failed / llm_deployment_not_found / llm_quota_exceeded escalate on the first occurrence (configuration/billing issues)
• Not counted: llm_content_filtered (a content issue, not a service issue)
• Deduplication: each session is notified only once; any successful sentence translation resets the counter, and the event can be triggered again
• payload: type: "error", without sid; details contains provider, last_error_code, fail_count
• Viewer notification: in broadcast mode, all viewers (regardless of language) also receive this event (through the SSE/WS broadcast channel)

TTS Synthesis Errors

Recording Errors

Processing Status Mismatch (invalid_processing_status)

This error code is used by POST /api/v1/tasks/{taskId}/force-fail and POST /api/v1/tasks/{taskId}/retry, returned when the recording status does not meet the operation's prerequisites. The details field helps further identify the trigger reason:

File Import Errors

Note: If the monthly budget has been exceeded at upload time, the auth_budget_exceeded error (HTTP 402) is returned.

Storage Errors

SSE Errors

Broadcast Errors

Conversation Errors

Handling strategy:

conversation_requires_two_languages error details:

This error occurs in the start action of type: "conversation" when the number of transcription_languages is not 2.

{
  "type": "error",
  "data": {
    "error_code": "conversation_requires_two_languages",
    "severity": "error",
    "message": "Conversation mode requires exactly 2 languages",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "received_count": 1,
      "expected_count": 2
    }
  }
}

conversation_languages_identical error details:

This error occurs in the start action of type: "conversation" when the two provided transcription_languages are the same.

{
  "type": "error",
  "data": {
    "error_code": "conversation_languages_identical",
    "severity": "error",
    "message": "Conversation languages must be different",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "languages": ["zh-TW", "zh-TW"]
    }
  }
}

conversation_invalid_language error details:

This error occurs during switch_language when the specified language is not in the conversation language pair.

{
  "type": "error",
  "data": {
    "error_code": "conversation_invalid_language",
    "severity": "error",
    "message": "Language not in conversation languages",
    "context": "session",
    "request_id": "req_abc123xyz",
    "timestamp": "2026-03-04T10:30:45.123Z",
    "details": {
      "language": "ja-JP",
      "conversation_languages": ["zh-TW", "en-US"]
    }
  }
}

Summary Errors

Retranslation Errors

Language Switch Errors

Recording Name Errors

General Errors

Frontend Error Handling Example

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

  switch (severity) {
    case 'fatal':
      // Fatal error: stop the service and show an error page
      showErrorPage(message);
      disconnectWebSocket();
      break;

    case 'error':
      // Operation failed: show an error prompt and allow retry
      showErrorToast(message);
      break;

    case 'warning':
      // Warning: show a warning without blocking the operation
      showWarningToast(message);
      break;
  }

  // Log the error for debugging
  console.error(`[${error_code}] ${message}`);
}

Version: V1.5.7 Last Updated: 2026-05-20