Errors & response envelope

The standard JSON envelope and HTTP status codes used by the Voice API.

Response envelope

JSON endpoints return a consistent envelope with a boolean error flag. On success, error is false and the payload is in data:

{
  "status": 200,
  "data": { "...": "endpoint payload" },
  "error": false
}

On failure, error is true, data is omitted, and message carries the detail:

{
  "status": 422,
  "error": true,
  "message": "audio_too_short"
}

The audio endpoints don’t use this envelope on success: /speak returns raw audio bytes and /stream returns a Server-Sent Events body. Errors on those endpoints still return the JSON envelope above.

Plan-limit & entitlement denials

Billing-related denials do not use the standard envelope - they return a flat JSON body.

Per-resource plan limits (for example creating more voices than your plan allows) return 403:

{
  "error": "plan limit reached",
  "feature": "max_voices",
  "limit": 10
}

When metered-usage enforcement is active, an exhausted allowance returns 402, and a feature your plan doesn’t include returns 403. Both carry the unit and the current usage:

{
  "error": "quota_exhausted",
  "unit": "character",
  "limit": 100000,
  "used": 100000
}

The error string is the denial reason (e.g. quota_exhausted, insufficient_credits, limit_reached, or feature_disabled).

Status codes

Status	When it happens
200	Success (GET, and the audio/stream endpoints).
201	Resource created.
202	Accepted - asynchronous enroll/clone job started.
400	Invalid request - missing/invalid field, text too long (> 10,000 chars), or the voice isn’t ready yet.
401	Missing or invalid X-API-Key.
402	Metered allowance exhausted (billing enforcement) - see plan-limit denials above.
403	Not permitted, a plan limit was reached, or a feature is disabled for your plan.
404	Voice or resource not found - including voices owned by another workspace.
422	The voice provider rejected the input (for example, a reference clip that’s too short).
429	Rate limited - retry after a short delay.
502	The voice provider is temporarily unavailable.

Common messages

Voice is not enrolled yet

The voice you referenced isn’t ready to use - only voices with status ready can synthesize. See Working with voices.

text too long (max 10000 chars)

The text field exceeds the 10,000-character limit. Split long input into multiple requests.

Provider errors (422 / 429 / 502)

These originate from the upstream synthesis provider. 422 is a validation issue with your input, 429 is rate limiting, and 502 means the provider is warming up or unavailable - retry with backoff.