Server Error Handling

Server SDK error handling is language-specific. Do not assume that Python’s structured fields or error-code enum also exist in Go.

Python

The Python SDK exposes structured SessionTokenError and AvatarSDKError instances. Use their stable code for program logic and log context fields such as failure phase, HTTP status, server details, correlation IDs, and WebSocket close information when present. The complete field list and AvatarSDKErrorCode values live in the Python SDK error reference.

Go

The Go SDK returns standard Go error values from session operations and sends asynchronous failures to the callback configured with WithOnError. Log the full error and preserve the operation that produced it. See the Go SDK reference for its current public surface. Do not branch on Python AvatarSDKErrorCode values in Go code unless the installed Go SDK explicitly exports an equivalent typed error.

Recovery policy

Failure area	Recommended handling
Credentials or application configuration	Stop retrying and surface the problem to operators.
Session Token creation	Check API Key, App ID, expiry, account state, and selected region.
WebSocket connection	Retry transient network failures with bounded exponential backoff.
Audio or request validation	Fix the payload before retrying.
Unexpected runtime close	Log close details and correlation IDs, then create a new session if retryable.
Repeated upstream or server failure	Stop the retry loop and alert operators or contact Spatius support.

Never log the API Key or complete Session Token while collecting diagnostic context.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Handling

Server Error Handling

Python

Go

Recovery policy

​Python

​Go

​Recovery policy

Python

Go

Recovery policy