Errors

The API uses standard HTTP status codes. A 2xx status means success. Anything else comes with a JSON body holding a readable message in error:

{
  "error": "Text exceeds 5,000 character limit"
}

Show the message to your developers, but branch your code on the status code: messages can be reworded over time.

Status codes

Status	Meaning	Retry?
`200`	Success.
`400`	The request is invalid: a field is missing or malformed, or the text is too long.	No. Fix the request.
`401`	The API key is missing, wrong or revoked.	No. Check the key.
`402`	Your API credit can't cover the request.	After you top up.
`413`	The file or request body is too large.	No. Send less.
`429`	Too many requests per minute, or too many at once.	Yes, after a pause.
`500`, `503`	Something went wrong on our side.	Yes, with backoff.
`502`	The voice engine didn't return audio.	Yes, with backoff.

Failed requests are never charged, so retrying a 429, 500, 502 or 503 is safe. See Going to Production for a retry helper.

Status	Error	What to do
`400`	`text is required`	Send `text`, or `segments` with at least one non-empty line.
`400`	`Text exceeds 5,000 character limit`	Split the text into several requests.
`400`	`segments must be a non-empty array`	Send `segments` as an array of lines.
`400`	`A dialogue can have at most 40 lines`	Split the dialogue into several requests.
`400`	`Pick a voice from your voice library first.`	With `quality: "clone"`, use the ID of a voice in your library.
`400`	`Pick a voice from your voice library for every speaker.`	With `quality: "clone"`, every line's `voiceId` must be in your library.
`502`	`The voice engine returned no audio. Please try again.`	Retry.

Status	Error	What to do
`400`	`audio is required ...`	Send the file in a multipart field named `audio`, or base64 audio in a JSON `audio` field.
`400`	`Unsupported audio format. Use mp3, wav, webm, ogg, m4a, or flac.`	Convert the file to a supported format.
`400`	`Upload error: ... Send the file in the "audio" field.`	Name the multipart file field `audio`.
`400`	`Audio is empty or not valid base64`	Check the base64 encoding of the JSON `audio` field.
`413`	`Audio file exceeds 25 MB size limit`	Send a smaller or more compressed file.

Status	Error	What to do
`401`	`Missing or invalid Authorization header`	Send your key in the `x-api-key` header.
`401`	`Invalid or revoked API key`	Check the key, or create a new one.
`402`	`Insufficient API balance ($0.00). This request needs ...`	Top up under API Billing.
`413`	`request entity too large`	Keep JSON bodies under 10 MB.
`429`	`Too many requests`	Wait for the number of seconds in the `Retry-After` header.
`429`	`Too many concurrent API requests (max 5). ...`	Wait for running requests to finish, or top up to unlock more.
`500`	`Internal server error`	Retry with backoff. If it persists, contact support.