Errors and retries

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.

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.

Get started

Console

Workflows

Session API

API reference

Help

Errors and retries

Safe launch retries

​Safe launch retries

Safe launch retries