Error Handling

Error response format and status codes.

All errors follow a consistent format. Check success: false and read the error field for details.

Error Response Format

{
  "success": false,
  "error": "Human-readable error description"
}

Error Codes

HTTP Code	Meaning	When it happens	What to do
400	Bad Request	Missing or invalid parameters (e.g. missing `script`, invalid `url`, `max_videos` out of range, invalid `job_id`)	Check your request parameters against the endpoint docs
401	Unauthorized	API key is missing, invalid, or deactivated	Verify your API key is correct and active
402	Payment Required	Not enough TTS or studio credits for this request	Purchase more credits from your dashboard
403	Forbidden	Feature requires a higher plan. Voice generation (TTS, voice listing, voice cloning) and caption removal require Professional or Ultimate. All other features are available on Starter.	Upgrade your plan in Settings
404	Not Found	Resource does not exist (e.g. `job_id` not found, voice not found)	Verify the ID is correct and belongs to your account
429	Too Many Requests	Either the per-minute rate cap for your API key was exceeded (30 RPM default / 100 RPM for channel-info / 60 RPM for status), or your tier's concurrent-job cap was reached (8 Starter / 20 Professional / 40 Ultimate; image generations have their own bucket of 10 / 25 / 50). The `error` message tells you which.	Rate cap: back off for the seconds named in the error. Concurrent jobs: wait for one to finish.
500	Server Error	Unexpected internal error	Retry the request. If persistent, contact support.