SDK Error Reference
This page provides a comprehensive reference of all error types and codes that can be returned when using the Vonage Client SDK. Understanding these errors will help you implement proper error handling in your application.
Error Structure
All errors in the Client SDK are instances of VonageError with the following properties:
| Property | Type | Description |
|---|---|---|
type | string | The category of error (see Error Types below) |
code | string | Specific error code identifying the exact error |
message | string | Human-readable description of the error: what happened, where, and what to do |
source | string | A short trace of the code path that failed. Send it, with the code, when you contact Vonage support |
isRetriable | boolean | Whether the failure is transient and worth retrying |
retryAfter | number | Optional. How long to wait before retrying, when the server said so |
For the cause of each error and what to do about it, see Troubleshooting.
Error Types
The SDK uses the following error type categories:
| Error Type | Description |
|---|---|
CS_ERROR | Backend service errors (API errors from Vonage backend services) |
SESSION_ERROR | Authentication and session-related errors |
NETWORK_ERROR | Network connectivity issues, timeouts, and HTTP 5xx server errors |
INTERNAL_ERROR | SDK-generated errors including media errors, validation, and parsing issues |
UNKNOWN_ERROR | Unexpected errors that should be reported to support |
Complete Error Code Reference
CS_ERROR Codes
Backend service errors returned from the Vonage API:
| Error Code | HTTP Code | Description |
|---|---|---|
http:error:db-unavailable | 500 | Database is temporarily unavailable |
http:error:service-not-available | 503 | Service is temporarily unavailable |
http:error:not-found | 404 | Endpoint does not exist or you do not have access |
SESSION_ERROR Codes
Authentication and authorization errors:
| Error Code | Description |
|---|---|
internal:auth:authorization_error | Invalid or missing authorization token |
system:error:expired-token | The provided token has expired |
system:error:invalid-token | The provided token is invalid |
system:error:missing-token | No token was provided |
NETWORK_ERROR Codes
Network and connectivity errors:
| Error Code | HTTP Code | Description |
|---|---|---|
internal:error:serviceNotAvailable | 503 | Service temporarily unavailable, retry recommended |
http:error:internal | 500 | Internal server error, try again shortly |
INTERNAL_ERROR Codes
SDK-generated errors including media, validation, and parsing issues:
Media Errors
| Error Code | Description |
|---|---|
voice:error:media_timeout | Emergency calls only: the call's media connection failed or closed before the call connected |
voice:error:media_setup_failed | serverCall / answerCall: this device's audio never reached Vonage, after retries |
voice:error:media_connection_lost | serverCall: the call was placed, but this device's audio connection dropped before it connected |
voice:error:call_not_confirmed | serverCall: the call was placed with healthy connections, but Vonage did not confirm it started |
voice:error:call_already_ended | answerCall: the call ended before it could be answered |
voice:error:websocket_signaling_connection_lost | The signaling WebSocket connection dropped while setting up a call and did not recover |
voice:error:no_call_found | No emergency call found with the specified call ID |
voice:error:no_call_media_found | No call media found for the specified call |
voice:error:no_offer_found | No SDP offer was generated for the call |
voice:error:no_answer_found | No SDP answer was received for the call |
media:error:media_not_found | Media connection not found for the specified call ID |
media:error:peer_connection_not_found | WebRTC peer connection not found for the specified call ID |
media:error:track_not_found | Audio track not found for the specified call ID |
media:error:create_answer_error | Failed to create SDP answer |
media:error:create_offer_error | Failed to create SDP offer |
media:error:create_media_error | Failed to create local media |
media:error:process_answer_error | Failed to process SDP answer |
media:error:process_offer_error | Failed to process SDP offer |
media:error:audio_transformer_error | Error in audio processing/transformation |
media:error:noise_suppression_already_enabled | Noise suppression is already enabled |
media:error:noise_suppression_already_disabled | Noise suppression is already disabled |
media:error:noise_suppression_models_not_found | Noise suppression models not found |
media:warning:no_microphone_audio | Connected call: this device is not capturing audio from the microphone (reported through onCallMediaWarning) |
media:warning:audio_not_sent | Connected call: the microphone captures audio, but this device is not sending it |
media:warning:audio_not_reaching_vonage | Connected call: this device sends audio, but Vonage is not receiving it |
media:warning:no_audio_from_vonage | Connected call: no audio is reaching this device from Vonage |
media:warning:remote_audio_silent | Connected call: audio reaches this device, but it is silent |
Validation and Parsing Errors
| Error Code | Description |
|---|---|
internal:error:parsing_exception | Failed to parse response from server |
internal:error:unsanitized_input_error | Request contains unsanitized input and was rejected |
internal:error:illegal_argument_exception | Incorrect arguments provided to method |
internal:error:unexpected_null_value | Unexpected null value encountered |
Emergency-Specific Errors
| Error Code | Description |
|---|---|
emergency:error:invalid_reconnect_token_origin | Reconnect token is missing or has invalid origin |
emergency:error:call_timeout | Emergency call operation timed out |
UNKNOWN_ERROR
| Error Code | Description |
|---|---|
| N/A | Unexpected error that doesn't fit other categories - should be reported to support |