Troubleshooting

401 UnauthorizedCopy Anchor Link

• The key was revoked or rotated — the old secret stops working within ~30 seconds.
• The header is missing: it must be X-Api-Key, not Authorization.

The browser says "blocked by CORS policy"Copy Anchor Link

You called the API from page JavaScript. Even where a browser could make the call, 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 RequiredCopy Anchor Link

Read the error field:

400 Bad Request on createCopy Anchor Link

• invalid_zip / invalid_manifest: the message names the entry or field. Common: two files in image/, a prompt.txt together with persona.scenario, visibility: public on create.
• invalid_url (JSON create): an asset URL is not https, carries credentials, or resolves to a private, loopback or link-local address. Host the files publicly.
• fetch_failed (JSON create): the URL could not be downloaded — unreachable, a non-2xx answer, or more than three redirects. The message names the URL.
• invalid_upload: a file has the wrong type or exceeds its size limit.

403 ForbiddenCopy Anchor Link

• insufficient_scope: the key lacks the scope this call needs (avatars:write to create or change avatars, billing:write to fund them, generation:write and avatars:write to generate). Add the scope in Studio → API, or create a key with the right scopes.
• 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_foundCopy Anchor Link

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 ConflictCopy Anchor Link

• avatar_busy: the avatar is already in a live conversation of your account; an avatar holds one at a time, and nothing is billed for the refused start. End the other session (POST /v1/sessions/{id}/end, with the liveSessionId the error gives when it is an API session), wait for it to end, or start with another avatar.
• avatar_not_ready: an Atmee V2 avatar has no take serving yet. Poll GET /v1/avatars/{avatarId} until readyToChat is true, then start again.
• avatar_limit_reached: your plan's limit on API-created avatars (maxApiAvatars in GET /v1/account). Delete avatars you no longer need.
• idempotency_key_reused: the same Idempotency-Key was sent with a different avatar or amount.

422 Unprocessable EntityCopy Anchor Link

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

503 Service UnavailableCopy Anchor Link

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 audioCopy Anchor Link

• 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"Copy Anchor Link

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.