Errors

Response envelope

Every response uses a consistent envelope. Success:

{ "success": true, "data": { /* ... */ } }

Failure — success: false, data: null, and an error object with a machine-readable code:

{ "success": false, "data": null, "error": { "code": "UNAUTHORIZED" } }

Always branch on the HTTP status first, then read error.code for specifics.

Common HTTP statuses

Status	Meaning	What to do
`400`	Malformed request	Fix the request body/parameters.
`401`	Missing/invalid API key	Check the `X-API-Key` / `Authorization` header.
`402`	Out of credits	You’ve used your cycle’s credits — see Rate limits & quota.
`413`	Payload too large	Shorten `text`, or reduce the ASR audio file.
`415`	Unsupported media	Use a supported audio format (see ASR).
`422`	Validation error	A field failed validation (e.g. `text` length).
`429`	Too many requests	Back off and retry — see Rate limits.
`5xx`	Server error	Transient; retry with backoff.

Handling errors

Python

resp = requests.post(url, headers=headers, json=payload)

if resp.status_code == 429:
    # rate limited — wait and retry
    ...
elif not resp.ok:
    body = resp.json()
    code = (body.get("error") or {}).get("code")
    raise RuntimeError(f"{resp.status_code} {code}")

Streaming endpoints (/v1/speech/synthesize) signal failures with a non-200 status before the stream starts. Once a 200 NDJSON stream begins, check for an error record/early close if the connection drops mid-stream.

Retries

Retry 429 and 5xx with exponential backoff (e.g. 1s, 2s, 4s) and a cap. Do not retry 4xx other than 429 — fix the request instead.

Get Started

Models

Guides

Response envelope

Common HTTP statuses

Handling errors

Retries

​Response envelope

​Common HTTP statuses

​Handling errors

​Retries

Response envelope

Common HTTP statuses

Handling errors

Retries