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 a line that belongs to another account	Ask for the scope, or check the line 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 `tenantId` 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`	A line with this `externalId` already exists	Find it in the list and use it
`TENANT_QUOTA_EXCEEDED`	`402`	The line 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 `tenantId` to release the number, then retry
`TENANT_TERMINATED`	`409`	Changing settings on a terminated line	Create a new line
`TENANT_REGION_UNRESOLVED`	`409`	The line's record could not be found, so nothing was saved	Check the line 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
`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
Lines	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 a line 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

Line 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/tenants)
The response status and its error and code
The line's tenantId (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.