Error handling

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

Error responses

If an error occurs, Soniox will:

1. Send an error response containing an error code and error message.
2. Immediately close the WebSocket connection.

Example:

{
  "error_code": 400,
  "error_message": "Invalid model specified."
}

Always print out or log the error response to capture both the code and message.

The complete list of error codes and their meanings can be found under 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 are tolerated — such as brief buffering or network jitter — but prolonged bursts or lags may result in disconnection.