Error handling

All errors return a consistent JSON envelope. Handle errors by checking the HTTP status code first, then the error.code field for programmatic handling.

{
  "error": {
    "code": "LANGUAGE_NOT_SUPPORTED",
    "message": "The requested language is not available.",
    "request_id": "req_a1b2c3d4"
  }
}

HTTP STATUS	ERROR CODE	DESCRIPTION
400	INVALID_REQUEST	Malformed request body or missing required field.
401	UNAUTHORIZED	Missing or invalid API key.
404	LANGUAGE_NOT_SUPPORTED	Requested language is not available on this endpoint.
404	VOICE_NOT_FOUND	Requested voice ID does not exist for this language.
404	JOB_NOT_FOUND	The specified job_id does not exist.
422	AUDIO_PROCESSING_FAILED	Source audio could not be parsed or transcribed.
429	RATE_LIMIT_EXCEEDED	Request rate exceeds plan limits. See Retry-After.
500	INTERNAL_ERROR	Unexpected server error. Retry with exponential backoff.

All responses include a request_id. Include this in any support ticket to help us trace issues quickly.