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

Init failures are delivered as the rejection of init() without an error code.

Error Code	Category	Description
`STREAMING_FAILED`	Runtime	Remote track subscription failure — the connection is maintained
`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 cleans up its internal connection resources and returns to the 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' })
  .catch((error) => console.error(error.message));

Init failure itself is delivered as the rejection of init(), not through onError. However, onError may still fire for streaming-side issues during connection, so register onError before calling init().

message	Cause
`"Failed to connect: ..."`	SDK key validation or WebSocket connection failure
`"Failed to connect streaming: ..."`	Streaming connection failure
`"Init failed: ..."`	Other initialization failures

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). One exception: STREAMING_FAILED (remote track subscription failure) does not trigger connection cleanup or a return to IDLE — only onError is delivered.

Status Flow Per Error

Error Code	Trigger	State Transition
(init exception)	During init	`CONNECTING` or `SOCKET_CONNECTED` -> `IDLE`
`STREAMING_FAILED`	Runtime	No state transition — only `onError` is delivered, connection maintained
`SOCKET_DISCONNECTED_UNEXPECTEDLY`	Runtime	`CONNECTED_FINISH` -> connection cleanup -> `IDLE`
`STREAMING_DISCONNECTED_UNEXPECTEDLY`	Runtime	`CONNECTED_FINISH` -> connection cleanup -> `IDLE`
`SERVER_ERROR`	Runtime	`CONNECTED_FINISH` -> connection cleanup -> `IDLE`
`WORKER_DISCONNECTED`	Runtime	`CONNECTED_FINISH` -> connection 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
`STREAMING_FAILED`	`"Failed to subscribe to remote track"`	Remote track subscription failure — connection maintained, only `onError` is delivered
`SOCKET_DISCONNECTED_UNEXPECTEDLY`	`"WebSocket disconnected unexpectedly: {code}"` or `"Handover failed after max retries and active socket is dead"`	WebSocket abnormal termination
`STREAMING_DISCONNECTED_UNEXPECTEDLY`	`"Streaming disconnected: {reason}"` or `"Remote user left streaming"`	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 ​