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.

Connection lost without a close frame

A network path change between you and Soniox, for example a reroute at the CDN edge, can drop your WebSocket with status 1006 and no close frame. The server may not see the drop: your stream stays open and keeps its concurrent requests slot until it is ended by the 20-second keepalive timeout.

Reconnect right away. If many of your streams dropped at once and you are near your concurrent requests limit, the new streams may be refused with 429 Concurrent requests limit for real-time transcription has been exceeded for your organization (or project). The slots held by the dropped streams are freed within 20 seconds of the drop, so a 429 in this window is temporary: retry once the timeout has passed.

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.