Server SDK
For backend integrations, use your server SDK’s structured error information as the main reference. Server-side integrations should account for session token failures, WebSocket handshake failures, runtime server errors, and unexpected connection closures.Common server SDK error codes
These stable error codes are useful when building retry, logging, and alerting flows on your backend.| Error code | Meaning |
|---|---|
sessionTokenExpired | Session token expired or is no longer authorized |
sessionTokenInvalid | Session token is invalid or empty |
appIDUnrecognized | App ID is not recognized by the server |
appIDMismatch | Session token belongs to a different app |
avatarNotFound | Requested avatar does not exist |
billingRequired | Session is blocked by billing requirements |
creditsExhausted | Runtime or connect-time credits are exhausted |
sessionDurationExceeded | Session hit a billing-enforced duration limit |
unsupportedSampleRate | Audio sample rate is not accepted by the handshake |
invalidEgressConfig | LiveKit or Agora egress configuration is invalid |
egressUnavailable | Egress service is unavailable or not configured |
idleTimeout | Session was closed because no input was received |
upstreamError | Upstream internal service failed |
protocolError | Invalid protobuf payload or unexpected message sequence |
connectionFailed | Transport-level connection setup failed |
connectionClosed | WebSocket closed unexpectedly |
serverError | Server returned an unclassified error |
invalidRequest | Client request payload or parameters are invalid |
unknown | Fallback code when the SDK cannot classify the failure |
Server SDK error fields
When handling server SDK errors, check these fields to determine the correct recovery path:code: stable SDK error code for programmatic handlingphase: where the failure happened, such assession_token,websocket_connect, orwebsocket_runtimehttp_status: HTTP status for token or upgrade failuresserver_code,server_title,server_detail: normalized details returned by the serverconnection_id,req_id: correlation IDs for tracing requests in logsclose_code,close_reason: WebSocket close details for unexpected disconnects
Client SDK
For client-side troubleshooting, use the SDK-specific API and FAQ pages below.Web SDK
The Web SDK API reference includes a dedicated Error Codes section for controller and runtime failures.iOS SDK
Use theAvatarController.onError callback documented in the API reference to capture runtime failures and surface them in your app.
Android SDK
Use theAvatarController.onError callback documented in the API reference to handle rendering, networking, and playback failures on Android.
Recommended handling flow
- Log the SDK error code and phase.
- Capture server correlation identifiers when available.
- Retry only transient failures such as connection interruptions or timeouts.
- Surface configuration and authentication errors to operators with the linked SDK references.