Troubleshooting

401 Unauthorized

• The key was revoked or rotated — the old secret stops working within ~30 seconds.
• The key belongs to the other environment (staging key against api.atmanity.us, or the reverse).
• The header is missing: it must be X-Api-Key, not Authorization.

The browser says "blocked by CORS policy"

You called the API from page JavaScript. That is blocked on purpose — the key would be visible to every visitor. Move the call to your server and have the page call your endpoint (see the Quickstart).

402 Payment Required

Read the error field:

error	Fix
insufficient_credits	Top up your account under Studio → Billing.
api_key_spend_cap_reached	Raise or clear the key's spend cap under Studio → API, or wait for the window to reset.
concurrent_session_limit	Fewer parallel sessions, or a higher cap (up to your plan's maximum).
sponsor_budget_exhausted	The avatar's sponsor budget is empty — see Sponsored access.

403 Forbidden

• insufficient_scope: the key lacks the scope this call needs (avatars:write to create or change avatars, billing:write to fund them). Create a key with the right scopes — scopes cannot be added to an existing key.
• avatar_not_allowed, or no error body: the key is scoped to a different avatar, or the avatarId belongs to another account.

404 avatar_not_found

Wrong id, a deleted avatar, or an avatar that belongs to another account — the API never confirms that an avatar exists outside your account.

409 Conflict

• avatar_limit_reached: the per-account cap on API-created avatars (50). Delete avatars you no longer need.
• idempotency_key_reused: the same Idempotency-Key was sent with a different avatar or amount.

422 Unprocessable Entity

The request body failed schema validation — a field is missing, has the wrong type, or is outside its limits. The body is { "code": 422, "message": "..." } and the message names the field. Field limits are listed per endpoint in the Reference.

503 Service Unavailable

A transient error occurred or the service is out of capacity. Retry with exponential backoff and show the visitor a "try again shortly" state.

The room connects but there is no video or audio

• Attach both tracks the avatar publishes (video and audio) in TrackSubscribed.
• Autoplay with sound needs a user gesture — start the session from a click.
• If the visitor cannot be heard, the microphone permission was denied or the wrong device is selected. Let visitors pick a microphone; the built-in one is often not the default.

"Avatar not ready"

Sessions can only start once the avatar has finished building (previews generated). Check readyToChat on GET /v1/avatars/{avatarId}, or its status on Studio → Manage; a failed stage shows there with a retry.