Beta
API errors and troubleshooting
Browse documentation
Errors
Read the HTTP status first. Gateway errors normally include a JSON detail message, X-Error-Code for the machine-readable reason, and X-Request-Id to identify the request. Errors from a proxy or interrupted connection may not include these fields.
| Status | Meaning |
|---|---|
| 400 | Malformed body, unsupported response_format, or an unusable voice value. |
| 401 | Missing, revoked or unrecognised API key. |
| 402 | Not enough prepaid balance for the request. |
| 404 | The voice id does not exist or is not available to your account. |
| 413 | The request body exceeds the endpoint limit. Reduce the upload or input size before retrying. |
| 429 | Rate limit or concurrency limit. Retry with backoff. |
| 502 | The gateway could not complete the request with the speech service. Wait before retrying. |
| 503 | No capacity right now. Retry shortly. |
We refund requests that fail on our side before producing audio. Invalid options and unavailable voices are rejected before charging. A backend rejection of your request after charging, a client disconnect, or a partially delivered stream is not refunded.
Fix input, credentials or balance before retrying 400, 401, 402, 404 or 413 responses. For 429, 502 or 503, retry a limited number of times with increasing delays. Avoid parallel retry loops. If a connection breaks after submission, the outcome can be uncertain; another request can generate and charge again.
When contacting support, include the request ID, endpoint, HTTP status and approximate time. Do not include your API key or the recording itself.