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:

1. Send an error response with the fields below.
2. 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. While most sessions last until the maximum supported audio duration (see Limits & quotas), early termination may occur.

If a session is closed early, you’ll receive a 503 error:

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

Your application should:

• Detect this error.
• 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.