> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livefaces.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Diagnose failed requests and retry a launch without creating a second conversation.

API errors include `code`, `detail`, and `request_id`. The response also includes an `X-Request-ID` header. Keep the request ID for support; exclude API keys and participant tokens from logs.

| Status | Check or action |
| - | - |
| `401` | Verify the key is correct, unexpired, and not revoked. |
| `403` | Check the required scope and organization access. |
| `404` | Check the ID and organization. Read session resources with the key that created them. |
| `409` | The request conflicts with current state, including an idempotency key reused with changed parameters or an already terminal session. |
| `422` | Correct missing headers, IDs, fields, types, or workflow inputs. Unknown request fields are rejected. |
| `500` | Keep the request ID. Retry a launch only with the same attempt key and body. |
| `503` | Session creation is unavailable. Use bounded backoff; if it persists, check availability with the LiveFaces team. |

## Safe launch retries

Generate the attempt key **once**, before your first request. Persist it with the intended operation if a retry can happen in a later server request.

```js theme={null}
const attemptId = crypto.randomUUID();
const body = JSON.stringify({ voice_id: voiceId });

async function attempt() {
  return fetch("https://api.livefaces.ai/v1/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LIVEFACES_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": attemptId,
    },
    body,
  });
}
```

Call `attempt()` again with bounded backoff for retryable network or service failures. Do not change the body or attempt ID during those retries. A timeout can occur after the service accepted a request.

Use a new key for a deliberately new conversation. Correct validation and permission problems before retrying; repeatedly sending the same invalid request will not fix them.


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