Complete Error Code Reference

Table of Contents

• Error Response Format
• Severity Levels
• Authentication Errors
• Plan and Usage Limit Errors
• Ticket Authentication Errors
• Session Errors
• Speech Recognition Errors
• Audio Processing Errors
• Speaker Diarization Errors
• Multi-Channel Errors
• Speaker Errors
• Configuration Errors
• Record Type Restriction 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.

Also note that some fatal errors without sid do not close the connection (for example, auth_quota_exceeded and plan_feature_not_allowed); whether you need to reconnect depends on the description of each error code.

Authentication Errors

Plan and Usage Limit Errors

Applies to API Keys on an "unlimited plan" (added in v1.9.0; see Pricing — Unlimited Plans). When blocked by any of the errors below, use GET /api/v1/me/plan to look up "what does my plan include, how far am I from a limit, and when does the restriction lift".

The two occurrence points of plan_feature_not_allowed (WebSocket):

• start rejected: when the plan does not include a feature enabled in the request, the start is rejected; the connection is not closed — adjust the parameters and start again.
• Detected while recording: for example, a feature not in the plan is turned on mid-session; once the check before the next minute detects it, the current recording is stopped.

For real-time recording, usage limits are checked before each minute begins; once a limit is reached, the next minute does not start and is not counted toward usage. When the same API Key runs several recordings at once, after the periodic-stop threshold is reached, each recording stops before its own next minute begins.

REST scenarios returning HTTP 403: POST /api/v1/broadcasts (creating a broadcast with a plan-bound key — broadcasts are never included in unlimited plans), POST /api/v1/auth/tasks/{taskId}/subtitle-feed-token and subtitle-share (plan without floating subtitles), and POST /api/v1/imports (plan without audio import).

plan_daily_limit_reached (HTTP 402) occurs on POST /api/v1/auth/ticket and the import upload: when the plan's daily hard limit has been reached, new recordings / imports are blocked up front. The same string also appears as the data.reason of POST /api/v1/imports/check-quota; that endpoint is a read-only query and returns HTTP 200, not an error.

too_many_languages semantics extended (v1.9.0): details.max may come from the plan's cap on simultaneously recognized transcription languages, in addition to the system-wide limit (10 transcription languages); details carries max and received.

Ticket Authentication Errors

Session Errors

Speech Recognition Errors

Starting again after a recording is ended: after an error that ends the recording, such as stt_quota_exceeded, stt_silence_timeout, plan_feature_not_allowed, or daily_limit_disconnect, you can send start on the same connection immediately, but session_started arrives only after the previous recording finishes processing (after status: "ended"), which can take from a few seconds to a few tens of seconds depending on the summary length. Do not treat this as a timeout.

Audio Processing Errors

Speaker Diarization Errors

Multi-Channel Errors

Applies to multi-channel mode (recognition_mode: "multi_channel", added in v1.10.0; see WebSocket API Reference – Voice Translation for the parameters and channel operations, and Pricing for billing). All errors below are WebSocket errors with no corresponding HTTP status code.

Multi-channel semantics of existing error codes:

• invalid_recognition_mode: when the multi-channel feature is not enabled in this environment, a start with recognition_mode: "multi_channel" returns this error; details carries field: "recognition_mode" and received_value.
• invalid_parameter: returned on conflicting parameter combinations — multi_channel combined with speaker_diarization (multi-channel is itself a form of speaker separation); type: "conversation" combined with multi_channel; a set_channel_language that switches to the channel's current language, carries more than one language in transcription_languages, or provides both transcription_languages and language inconsistently; a channels[].speaker_name that is too long or contains control characters.
• plan_feature_not_allowed (details.field: "max_stt_streams"): the channel count in start or add_channel exceeds the unlimited plan's channel limit; details also carries max and the current count.
• too_many_languages: add_channel / set_channel_language introduces a new language that pushes the number of simultaneously recognized languages past the platform limit (10) or the plan's cap; details carries max / received / language.

There is also speaker_op_not_allowed_multi_channel (HTTP 422 on REST): for multi-channel recordings the speakers are determined by the channels, so speaker operations are limited to renaming; reassign and merge return this error both during recording (WebSocket) and afterwards (REST) — see Speaker Errors.

Speaker Errors

Configuration Errors

Record Type Restriction Errors

record (plain recording) is a lightweight speech-recognition-only type: translation and TTS are not supported, and summary is opt-in (generated only when summary_template or summary_mode=custom is provided). The following error codes are returned during the start phase when these restrictions are violated (since v1.7.0).

record_translation_not_allowed is also returned when calling retranslation endpoints (transcript retranslation, summary translation) on a record recording afterward.

Translation Service Errors

The HTTP column in this table is a semantic annotation, not the status code you will receive. Translation service errors are delivered almost entirely as stream events (SSE event: error or WebSocket type: error), and the stream itself always returns HTTP 200. This column indicates which class the error belongs to so you can choose a retry strategy: 4xx means the input needs to change, while 5xx and 429 mean you can retry later. Read error_code and severity; do not match this column against the status code you actually receive.

translation_service_unavailable trigger rules:

• Cumulative escalation: escalates after llm_timeout / llm_provider_error / llm_rate_limit / llm_request_failed fail repeatedly in a row
• 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

An HTTP column of — means the code is not returned as an HTTP status. It is delivered after the connection is established, through an error or tts_error event on the stream.

Recording Errors

Available Credit Fields (remaining_budget and budget_scope)

The details of auth_quota_exceeded and stt_quota_exceeded carry these two fields.

Important: remaining_budget is the credit available to the API key that made this request — not the end user's balance. If you call this service on behalf of other users, do not show this number directly to your end users; it reflects the state of your own key.

Note: Broadcasts are billed separately: even when a key is bound to a plan, broadcasts are charged by actual usage. So for a broadcast session these two codes carry budget_scope: api_key_credit and a real remaining_budget.

Processing Status Mismatch (invalid_processing_status)

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

Task Already Processing (task_already_processing)

POST /api/v1/tasks/{taskId}/retry returns this code when another processing run for the same task has not finished yet. Unlike invalid_processing_status, this condition is temporary: the request does not change the task status, and the same request succeeds once the previous run finishes.

Note: After a task fails, the system retries it automatically a few times. During that period processing_status may already read failed while a retry request still returns 409 — this means the automatic retries have not finished. No action is needed; send the same request again a few minutes later.

File Import Errors

Note: If the account has insufficient credit at upload time, the auth_insufficient_credit error (HTTP 402) is returned.

Codes with - in the HTTP column are not returned as HTTP status codes; they appear as the error_code of a failed import: in the import query API, in the failed event of the Import Progress SSE, and in the import.failed Webhook. The matching error_message is a fixed, general description without internal details; provide the import_id when you need troubleshooting.

Storage Errors

SSE Errors

Broadcast Errors

An HTTP column of — means the code is not returned as an HTTP status. It is delivered after the connection is established, through an error or tts_error event on the stream.

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.24.1 Last Updated: 2026-10-07