API · Reference

Errors

Errors use standard HTTP status codes and a JSON body with a detail field.

The body

// Most errors: a sentence
{"detail": "This key doesn't have the 'delete' permission."}

// Sessions: a code and a sentence
{"detail": {"code": "concurrency_limit", "message": "All sessions for this assistant are currently in use."}}

// Plan limits on setup routes
{"detail": {"error": "agent_limit", "message": "…", "upgrade": true}}

// A request that doesn't match the schema (422)
{"detail": [{"loc": ["body", "agent_id"], "msg": "Field required", "type": "missing"}]}

Read the status code first, then detail: a sentence you can show or log, or an object with a code (or error) your code can branch on.

Status codes

Status	Meaning	Retry?
400	A malformed request, or a DELETE without `?confirm=true`.	No, fix the request.
401	No key, a malformed Authorization header, or a revoked key.	No.
402	A plan limit: no balance, free minutes used, a premium feature on a free account.	After adding funds.
403	The key lacks the permission, or the account is not active.	No.
404	Not found in your account (agent, session, ticket…).	No.
409	The current state doesn't allow it: the agent's Brain is being built, or its concurrency limit is reached.	Yes, later.
422	The body or a value is invalid (unknown field, face, backdrop, camera…).	No, fix the request.
429	Too many requests.	Yes, after a short wait.
501	A live stage change the avatar host can't do yet.	No.
502 / 503	The avatar host didn't answer, or every avatar is busy (`no_capacity`).	Yes, with a short back-off.

Session error codes

code	Status	Meaning
`insufficient_balance`	402	A paid account's balance is used up.
`free_minutes_exhausted`	402	A free account used its 60 minutes this month.
`free_concurrency`	402	A free account already has a session running.
`paid_feature`	402	A premium voice on a free account.
`agent_not_found`	404	No such agent in your account.
`session_not_found`	404	No such session, or it isn't live.
`agent_building`	409	The agent's Brain is being built.
`concurrency_limit`	409	The agent is holding as many sessions as it may.
`voice_face_mismatch`	422	The voice doesn't suit the face.
`unknown_avatar`	422	No face with that id.
`invalid_look`	422	A backdrop, camera or face light that isn't valid.
`invalid_stage`	422	A live stage change with an unknown camera or backdrop.
`rate_limited`	429	More than 20 new sessions a minute.
`no_capacity`	503	Every avatar is busy right now.
`start_failed`	503	The avatar host didn't start the session. Try again.
`render_unavailable`	503	Render mode isn't available on the avatar host right now. Try again.

In render mode the socket has its own errors and close codes: see Streaming protocol.

Retrying well

•Retry 429, 502 and 503 with a growing wait (1 s, 2 s, 4 s…), a few times at most.
•Stopping a session is safe to repeat: stopping one that already ended answers the same way.
•Starting a session is not: if a start timed out on your side, list the live sessions before starting another.