Error handling

In the Soniox Real-time API, all errors are returned as a JSON error response before the connection is closed. Your application should always log and inspect these responses to determine the cause.

Error responses

If an error occurs, Soniox will:

Send an error response with the fields below.
Immediately close the WebSocket connection.

Example:

{
  "error_code": 400,
  "error_type": "model_not_available",
  "error_message": "Invalid model specified.",
  "more_info": "https://soniox.com/docs/api-reference/errors#model-not-available",
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda"
}

Branch your client code on error_type (stable across releases), not on error_message (human-readable, may change). Log the full response so the request_id is available when contacting support@soniox.com.

For the full catalog of error_type values, causes, and recovery steps, see the Errors reference. For the per-endpoint list of messages, see STT WebSocket error codes.

Request termination

Real-time sessions run on a best-effort basis.

Maximum session duration reached

A real-time session has a maximum supported duration (see Limits & quotas). When a session reaches this cap, the connection is closed with a 413 error:

This WebSocket connection has reached the maximum allowed duration and was closed. Please open a new WebSocket connection to continue transcribing.

error_type: max_duration_reached. Open a new WebSocket connection to continue streaming.

Early termination

A session may also be closed early (for example, on backend overload). In that case you’ll receive a 503 error:

Cannot continue request (code N). Please restart the request.

error_type: service_unavailable. Your application should detect this error and immediately start a new request to continue streaming.

Real-time cadence

You should send audio data to Soniox in real-time or near real-time speed. Small deviations such as brief buffering or network jitter are tolerated, but prolonged bursts or lags may result in disconnection.