Developers · API

Errors & limits

Every failure response has the same shape.

{
  "error": "A human-readable reason",
  "code": "MACHINE_READABLE_CODE"
}

error is always present; code is added only to failures your program needs to branch on. Branch on code; log and display error.

HTTP status codes

Status	Meaning	What to do
`400`	The request is malformed	Read `error` and fix the request. Retrying gives the same result
`401`	The key is missing, malformed or no longer valid	Check the header and key; if it persists, email support@livespeech.ai
`402`	Quota exceeded	Ask support@livespeech.ai to raise it
`403`	Missing scope, or an agent that belongs to another account	Ask for the scope, or check the agent identifier
`404`	No webhook registered	Register one first
`409`	Conflicts with the current state	Handle by `code`, below
`422`	The value itself breaks a policy (webhook URL or events)	Fix the value and send again
`429`	Too many requests	Wait a moment and retry
`502`	Termination held — a number is still attached	Email support@livespeech.ai with the `agentId` to release the number, then retry
`5xx`	A temporary server problem	Retry with a delay

Error codes

`code`	Status	When	What to do
`EXTERNAL_ID_EXISTS`	`409`	An agent with this `externalId` already exists	Find it in the list and use it
`AGENT_QUOTA_EXCEEDED`	`402`	The agent quota is exceeded	Ask support@livespeech.ai to raise it
`IDEMPOTENCY_KEY_MISMATCH`	`409`	The same idempotency key was reused with a different body	Use a new key
`IDEMPOTENCY_IN_PROGRESS`	`409`	The first request with this key is still running	Retry shortly with the same key
`ALREADY_TERMINATED`	`409`	A termination was recorded but its delegation release had not finished; this retry ran the release again	Nothing to do. Once termination is complete, a repeat `DELETE` answers `403` instead
`CARRIER_RELEASE_FAILED`	`502`	Termination held because a number is attached	Email support@livespeech.ai with the `agentId` to release the number, then retry
`AGENT_TERMINATED`	`409`	Changing settings on a terminated agent	Create a new agent
`AGENT_REGION_UNRESOLVED`	`409`	The agent's record could not be found, so nothing was saved	Check the agent identifier; if it persists, email support@livespeech.ai
`INVALID_CURSOR`	`400`	The cursor is invalid or has expired	Read again from the start without a cursor
`SUMMARY_NO_RECIPIENTS`	`400`	An empty recipient list would reach nobody	Keep at least one recipient
`SUMMARY_OWNER_LOOKUP_FAILED`	`503`	Looking up the recipient failed temporarily	Retry shortly (nothing was saved)
`WEBHOOK_URL_INVALID`	`422`	The webhook URL breaks the rules	Use `https`, a public host and no credentials
`UNKNOWN_EVENT`	`422`	An unsupported event name	Send only `call.completed`
`WEBHOOK_NOT_CONFIGURED`	`404`	No webhook registered	Register one with `PUT /v1/webhooks` first
`NUMBER_NOT_REQUESTED`	`404`	Number endpoint (opens with early access): reading status before any request was made	Request a number first (Phone numbers)
`NUMBER_ALREADY_CONNECTED`	`409`	Number endpoint: requesting a number for an agent that already has one	Nothing to do — the response carries the current number
`REGION_UNSUPPORTED`	`422`	Number endpoint: no numbers in the agent's region yet	`kr` and `ca` are available during early access
`persona.empty`	`400`	The persona is empty	Fill it in
`persona.too_long`	`400`	The persona is over 8,000 characters	Shorten it
`persona.tool_name`	`400`	The persona contains an internal feature name	Remove that word
`persona.tool_signature`	`400`	The persona contains code-like notation	Rewrite it as plain sentences

For persona.* codes, error is a Korean sentence you can show to the operator as is.

Limits

Item	Value
Rate limit	Per sending server IP + path, 30 requests per 5 minutes
Agents	Accounts may have a quota (`402` tells you)
List page size	1–200, default 50
Idempotency keys	Kept at least 24 hours; may be deleted after that
Webhook delivery attempts	8 in total including the first; retries start at 1 minute and double up to 1 hour
Webhook response timeout	10 seconds

Retry rules

This response	Retry
`429`, `5xx`, no response	Retry with a delay
`400`, `403`, `422`	Same result until you fix the request (a `403` on an agent you terminated means the termination is complete)
`409 IDEMPOTENCY_IN_PROGRESS`	Retry shortly with the same idempotency key
Any other `409`	Check the state, then send a different request

Agent creation needs an Idempotency-Key for retries to be safe — see the API reference.

Contact

Send questions to support@livespeech.ai. If you are stuck mid-integration, including the following speeds things up:

The method and path you called (for example POST /v1/agents)
The response status and its error and code
The agent's agentId (for call issues, the callId and the time of the call)
When you sent the request, with the time zone

Never put keys or secrets in a message. The key prefix (keyPrefix) is all that is needed.

About these docs

These docs are written from the API specification, and the example responses are taken from it. The API reference is generated from the specification on every deploy, so where a field differs, the reference is right.