Error Handling

SDK errors are delivered through 3 channels:

init errors — init() throws an Error
Runtime errors — Delivered via onError callback
Processing errors — Delivered as ERROR/REJECTED signals via onSignal (session maintained)

Error Codes

Error Code	Category	Description
`SOCKET_FAILED`	init	WebSocket connection failure or SDK key validation failure
`STREAMING_FAILED`	init	Agora streaming connection failure
`SOCKET_DISCONNECTED_UNEXPECTEDLY`	Runtime	WebSocket abnormal termination
`STREAMING_DISCONNECTED_UNEXPECTEDLY`	Runtime	Agora connection lost due to network issues, etc.
`SERVER_ERROR`	Runtime	SERVER_ERROR signal received from server
`WORKER_DISCONNECTED`	Runtime	Server connection termination signal received

init Errors

init() throws an Error on failure. The SDK automatically cleans up and returns to IDLE state.

JavaScriptReact

try {
  await SDK.init(options);
} catch (error) {
  console.error(error.message);
}

jsx

SDK.init({ sdk_key: 'YOUR_SDK_KEY', avatar_id: 'YOUR_AVATAR_ID' })
  .then(() => { initialized.current = true; })
  .catch((error) => console.error(error.message));

On init failure, onError is not called. Since init() throws an Error, handle it with try/catch.

message	Cause
`"Failed to connect: ..."`	SDK key validation or WebSocket connection failure
`"Failed to connect streaming: ..."`	Streaming connection failure

Runtime Errors

Errors that occur during active connections after init. Delivered via the onError callback.

When a runtime error occurs, the SDK automatically cleans up connections and returns to IDLE state. The client can reconnect by calling init() after receiving onError + onStatus(IDLE).

Status Flow Per Error

Error Code	Trigger	State Transition
(init throw)	During init	`CONNECTING` or `SOCKET_CONNECTED` -> `IDLE`
`SOCKET_DISCONNECTED_UNEXPECTEDLY`	Runtime	`CONNECTED_FINISH` -> cleanup -> `IDLE`
`STREAMING_DISCONNECTED_UNEXPECTEDLY`	Runtime	`CONNECTED_FINISH` -> cleanup -> `IDLE`
`SERVER_ERROR`	Runtime	`CONNECTED_FINISH` -> cleanup -> `IDLE`
`WORKER_DISCONNECTED`	Runtime	`CONNECTED_FINISH` -> cleanup -> `IDLE`

Init errors are thrown by init(), while runtime errors are delivered via onError callback + onStatus(IDLE).

Error Handling Example

SDK.onError((error) => {
  console.error('SDK Error:', error.code, error.message);
});

Error Code	message	Cause
`SOCKET_DISCONNECTED_UNEXPECTEDLY`	`"WebSocket disconnected unexpectedly: {code}"`	WebSocket abnormal termination
`STREAMING_DISCONNECTED_UNEXPECTEDLY`	`"Streaming disconnected: {reason}"`	Agora connection lost due to network issues, etc.
`SERVER_ERROR`	Server message or `"SERVER_ERROR"`	SERVER_ERROR signal received from server
`WORKER_DISCONNECTED`	Server message or `"WORKER_DISCONNECTED"`	Server connection termination signal received

Processing Error Signals

ERROR and REJECTED signals do not terminate the session. They indicate failures for individual requests. Received via onSignal (not onError).

SDK.onSignal((data) => {
  if (data.signal === 'ERROR') {
    // Server processing error
    console.warn('Error:', data.payload?.type);
  }
  if (data.signal === 'REJECTED') {
    // Invalid input
    console.warn('Rejected:', data.payload?.type);
  }
});

Signal	payload.type examples	Description
`ERROR`	`STT_ERROR`, `LLM_ERROR`, `TTS_ERROR`	Server internal processing error
`REJECTED`	`STT_EMPTY`, `MODERATION`	Input validation failure or policy violation

Error Handling ​

Error Codes ​

init Errors ​

Runtime Errors ​

Status Flow Per Error ​

Error Handling Example ​