> ## Documentation Index
> Fetch the complete documentation index at: https://spatialwalk-6179c111.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Error Codes

> iOS, Android, and Web SDK error codes with recovery guidance

All client SDKs surface errors through the `AvatarController.onError` callback as `AvatarError`.

**Web**

```typescript theme={null}
controller.onError = (error: AvatarError) => {
  console.error('Error:', error.code, error.message)
}
```

**iOS**

```swift theme={null}
controller.onError = { error in
    print("Error: \(error)")
}
```

**Android**

```kotlin theme={null}
controller?.onError = { error ->
    Log.e("Avatar", "Error: ${error.message}")
}
```

## Web — ErrorCode

| Code | Description | Recovery |
| - | - | - |
| `appIDUnrecognized` | App ID not recognized. | Verify your app ID in the dashboard. |
| `sessionTokenInvalid` | Session token is invalid or appId mismatch. | Verify token generation on your server. |
| `sessionTokenExpired` | Session token has expired. | Request a new token from your server. |
| `insufficientBalance` | Account balance is insufficient. | Top up your account in the dashboard. |
| `sessionTimeout` | Session timed out. | Reconnect by calling `start()` again. |
| `concurrentLimitExceeded` | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
| `avatarIDUnrecognized` | Avatar ID not found. | Check the avatar ID exists and is published. |
| `failedToFetchAvatarMetadata` | Failed to fetch avatar metadata. | Check network connectivity and retry. |
| `failedToDownloadAvatarAssets` | Failed to download avatar assets. | Check network connectivity and retry. |
| `serverError` | Server-side error. | Check the error message for details. |

## iOS — AvatarError

| Error | Description | Recovery |
| - | - | - |
| `appIDUnrecognized` | App ID not recognized. | Verify your app ID in the dashboard. |
| `sessionTokenInvalid` | Session token is invalid or appId mismatch. | Verify token generation on your server. |
| `sessionTokenExpired` | Session token has expired. | Request a new token from your server. |
| `insufficientBalance` | Account balance is insufficient. | Top up your account in the dashboard. |
| `sessionTimeout` | Session timed out. | Reconnect by calling `start()` again. |
| `concurrentLimitExceeded` | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
| `avatarIDUnrecognized` | Avatar ID not found. | Check the avatar ID exists and is published. |
| `avatarAssetMissing` | Avatar asset is missing locally. | Re-download with `AvatarManager.load()`. |
| `failedToFetchAvatarMetadata` | Failed to fetch avatar metadata. | Check network connectivity and retry. |
| `failedToDownloadAvatarAssets` | Failed to download avatar assets. | Check network connectivity and retry. |
| `serverError(code, message)` | Server-side error. | Check the error message for details. |

## Android — AvatarError

| Error | Description | Recovery |
| - | - | - |
| `AppIDUnrecognized` | App ID not recognized. | Verify your app ID in the dashboard. |
| `SessionTokenInvalid` | Session token is invalid or appId mismatch. | Verify token generation on your server. |
| `SessionTokenExpired` | Session token has expired. | Request a new token from your server. |
| `InsufficientBalance` | Account balance is insufficient. | Top up your account in the dashboard. |
| `SessionTimeout` | Session timed out. | Reconnect by calling `start()` again. |
| `ConcurrentLimitExceeded` | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
| `AvatarIDUnrecognized` | Avatar ID not found. | Check the avatar ID exists and is published. |
| `AvatarAssetMissing` | Avatar asset is missing locally. | Re-download with `AvatarManager.load()`. |
| `FailedToFetchAvatarMetadata` | Failed to fetch avatar metadata. | Check network connectivity and retry. |
| `FailedToDownloadAvatarAssets` | Failed to download avatar assets. | Check network connectivity and retry. |
| `ServerError(message, code)` | Server-side error. | Check the error message for details. |

## Recommended Handling Flow

1. Log the error code and current lifecycle phase.
2. Retry transient network/download failures with backoff.
3. Refresh session token for auth-related errors.
4. Surface configuration errors to developers/operators.

For platform-specific API details, see:

* [Web SDK API reference](https://spatialwalk-6179c111.mintlify.site/sdk-reference/web-sdk/api-reference.md)
* [iOS SDK API reference](https://spatialwalk-6179c111.mintlify.site/sdk-reference/ios-sdk/api-reference.md)
* [Android SDK API reference](https://spatialwalk-6179c111.mintlify.site/sdk-reference/android-sdk/api-reference.md)


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