Error Handling

WebSocket responses include structured error objects. Differentiate between connection-level failures and recoverable synthesis issues.

Unrecoverable Errors

Connection handshake or authentication failures close the socket immediately.

1
{
2
  "type": "error",
3
  "success": false,
4
  "error_name": "ConnectionFailure",
5
  "message": "Failed to establish a connection.",
6
  "status_code": 401
7
}

Typical causes: invalid token, plan lacks WebSocket access, network filtering.

Recoverable Errors

Synthesis-level problems keep the socket open so your client can retry.

1
{
2
  "type": "error",
3
  "success": false,
4
  "error_name": "BadJSON",
5
  "error_params": {
6
    "explanation": "Provide your query to synthesize as text or SSML in the 'data' field"
7
  },
8
  "message": "Invalid JSON: Provide your query to synthesize as text or SSML in the 'data' field",
9
  "status_code": 400
10
}

Handle recoverable errors by logging error_name, inspecting error_params, and prompting the user to resend a corrected payload.