Errors

When a request fails, the API returns an HTTP status and a JSON body with a human-readable error and a stable code. Branch on code, never on the message text.

Error shape

Error response

{
  "error": "Daily limit reached: 50,000 of 50,000 characters used today. Resets at 00:00 Sun 28 Sep.",
  "code": "QUOTA",
  "used": 50000,
  "limit": 50000,
  "resetsAt": "2026-09-27T17:00:00.000Z"
}

429 responses also carry a Retry-After header in seconds. The SDK throws VoixaError with the same status and code.

A body of the form {"message": "..."} with no error came from the API gateway before your request reached Voixa. See Gateway errors.

Request and account errors

Status	Code	Meaning	What to do
400	`INVALID`	The body or query failed validation; `error` names the field.	Fix the request.
403	`NOT_APPROVED`	The account is waiting for approval.	Contact us.
404	—	The voice, clip or transcript does not exist or is not yours.	Check the id.
409	`VOICE_NOT_READY`	The voice is still `processing` (or `failed`).	Wait for the clone to be ready.
409	`CLIP_NOT_READY`	You tried to share a clip that is not `ready`.	Share it once it is ready.
429	`QUOTA`	Daily character allowance reached.	Wait for `resetsAt`, or ask for more.
429	`AUDIO_QUOTA`	Daily transcription allowance reached.	Wait for `resetsAt`.
403	`CLONE_LIMIT`	Your account has as many clones as it may hold (`used`, `limit`).	Delete one, or ask for more.

Voice cloning errors

Status	Code	Meaning
400	`NO_REFERENCE`	`POST /voices` before the recording was uploaded to `uploadUrl`.
400	`REFERENCE_EMPTY`	The uploaded file is empty or too short to be speech.
400	`REFERENCE_TOO_LARGE`	The recording is over 10 MB. Ten seconds of speech is plenty.
400	`INVALID`	The language has no voice cloning (Chinese, Japanese, Korean).

A synthesis or transcription that fails after the request was accepted does not return an error: the object turns "status": "failed" with a readable failReason, and its characters or seconds go back to your allowance. For transcripts this includes a file over 5 GB or eight hours, an empty file, and an upload that never arrived. Retry with a new request.

Gateway errors

Response	Meaning
`403 {"message":"Forbidden"}`	Missing or wrong `x-api-key` — or a key created in the last few minutes.
`429 {"message":"Too Many Requests"}`	The key went over its request rate or daily call count.
`504 {"message":"Endpoint request timed out"}`	Rare; retry. `speak` answers well within the gateway's time limit.