How to classify and recover from AvatarKit loading, connection, audio, playback, and runtime errors.
Handle a client error according to where it occurred in the lifecycle. Exact error names and associated values differ by platform; use the SDK Reference as the source of truth.
Verify the avatar-id, then retry transient downloads.
Direct Mode authentication
Invalid or expired Session Token
Request a fresh token from your backend before reconnecting.
Direct Mode connection
Handshake, WebSocket, timeout, or unexpected close
Check region and network reachability, then reconnect with backoff.
Audio input
Input does not match the configured codec or sample rate
Convert the source and keep one configured format for the session.
Playback
Audio context or render player is not ready
Restore the required client lifecycle before retrying playback.
Backend Mode feed
Invalid or mismatched audio or motion data
Verify the configured format and ordering by turn ID.
Server response
Motion Server reports an application, billing, or runtime failure
Log the complete error and fix non-transient configuration failures before retrying.
Spatius API Keys must never be used for client recovery. In Direct Mode, the backend exchanges the API Key for a short-lived Session Token and returns only that token to the client.
