Client Error Handling

Lifecycle area	Representative signal	First action
Avatar loading	Unknown ID, metadata failure, asset download failure	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.

Lifecycle area

Representative signal

First action

Avatar loading

Unknown ID, metadata failure, asset download failure

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.

Recovery flow

Log the error, integration, SDK version, region, and current lifecycle phase.

Retry only network and download failures that are likely to be transient.

Refresh credentials for authentication failures instead of repeatedly reconnecting with the same token.

Treat format, asset compatibility, and application configuration failures as developer errors.

Stop automatic retries after a bounded number of attempts and surface a recoverable UI state.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Handling

Client Error Handling

Recovery flow

Exact platform errors

​Recovery flow

​Exact platform errors

Recovery flow

Exact platform errors