# Troubleshooting

URL: https://www.atmee.ai/docs/v2/api/troubleshooting

> The status codes you are most likely to hit, what they mean, and the browser issues behind a silent room.

## `401 Unauthorized`

* 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"

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](/docs/v2/api/quickstart)).

## `402 Payment Required`

Read the `error` field:

| `error`                     | Fix                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `insufficient_credits`      | Buy an add-on credit pack 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 owner funds this avatar's visitor chats from Studio → Billing and that budget is empty. |

## `400 Bad Request` on create

* `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 Forbidden`

* `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_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_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 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 [API reference](/docs/v2/api/reference/session/createSession).

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