> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Error Handling

> 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.

| 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. |

<Warning>
  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.
</Warning>

## Recovery flow

1. Log the error, integration, SDK version, region, and current lifecycle phase.
2. Retry only network and download failures that are likely to be transient.
3. Refresh credentials for authentication failures instead of repeatedly reconnecting with the same token.
4. Treat format, asset compatibility, and application configuration failures as developer errors.
5. Stop automatic retries after a bounded number of attempts and surface a recoverable UI state.

## Exact platform errors

* [Web SDK error handling](/sdk-reference/web-sdk/reference#error-handling)
* [iOS `AvatarError`](/sdk-reference/ios-sdk/api-reference#avatarerror)
* [Android SDK reference](/sdk-reference/android-sdk/api-reference)
* [Flutter SDK reference](/sdk-reference/flutter-sdk/api-reference)
* [Web RTC Adapter](/sdk-reference/web-sdk/rtc-adapter)

For backend failures, see [Server Error Handling](/resources/server-error).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.