Error codes
The full set of error codes, grouped by cause. Codes are stable — safe to match on.
Updated Nov 17, 2026 The full set of error codes, grouped by what caused them. Codes are stable, so they're safe to match on in your integration.
Authentication & access
| HTTP | Code | Meaning |
|---|
| 401 | MISSING_API_KEY | No x-api-key header was sent. |
| 401 | INVALID_KEY_FORMAT | The key doesn't start with jsf_ or is too short. |
| 401 | INVALID_API_KEY | The key doesn't match any account. |
| 403 | SUBSCRIPTION_INACTIVE | The account's subscription is turned off. |
| 403 | KEY_EXPIRED | The key's expiry date has passed. |
| 503 | AUTH_SERVICE_ERROR | Authentication was briefly unavailable. Retry shortly. |
Request & quota
| HTTP | Code | Meaning |
|---|
| 429 | RATE_LIMITED | Over the limit for this endpoint. Wait Retry-After seconds. |
| 400 | INVALID_JSON | Text-to-speech body wasn't valid JSON. |
| 400 | INVALID_CONTENT_TYPE | Clone body wasn't multipart/form-data. |
| 422 | VALIDATION_ERROR | One or more fields or query parameters are invalid. See fields. |
| 402 | INSUFFICIENT_CHARACTERS | Not enough character balance for this request. |
| 402 | UPGRADE_REQUIRED | Voice cloning needs a plan with at least 10,000 available characters. |
| 405 | METHOD_NOT_ALLOWED | The endpoint doesn't accept this HTTP method. |
Voices
| HTTP | Code | Meaning |
|---|
| 400 | INVALID_VOICE_ID | The voice_id is not a valid jsf_ ID. |
| 404 | VOICE_NOT_FOUND | The voice doesn't exist, or isn't on your account. |
| 403 | CANNOT_DELETE_DEFAULT_VOICE | Default voices can't be deleted. |
| 422 | VOICE_UNSUPPORTED | This voice has no stored sample. Clone it again. |
| 503 | VOICE_LOOKUP_FAILED | Voices couldn't be loaded. Retry shortly. |
| 500 | DELETE_FAILED | The voice couldn't be deleted. Retry. |
Cloning
| HTTP | Code | Meaning |
|---|
| 422 | AUDIO_REJECTED | The sample couldn't be processed. Use a clearer 10–30s recording. |
| 413 | AUDIO_TOO_LARGE | The sample exceeds the size limit. |
| 429 | CLONING_CAPACITY | The cloning engine is momentarily at capacity. Retry soon. |
| 503 | CLONING_SERVICE_DOWN | The cloning engine is temporarily unavailable. |
| 500 | SAMPLE_SAVE_FAILED | Your sample couldn't be stored. Retry. |
| 502 | CLONING_FAILED | Cloning failed unexpectedly. Retry. |
Text to speech
| HTTP | Code | Meaning |
|---|
| 422 | GENERATION_REJECTED | The engine couldn't process this text or voice. |
| 503 | ENGINE_UNAVAILABLE | Generation is temporarily unavailable. Retry shortly. |
| 503 | MODEL_UNAVAILABLE | The requested model is temporarily unavailable. Try jsf_fi. |
| 504 | GENERATION_TIMEOUT | Generation took too long. Try shorter text. |
| 502 | GENERATION_FAILED | Generation failed unexpectedly. Retry. |
| 502 | AUDIO_SAVE_FAILED | Audio was generated but couldn't be stored. Retry. |
Server
| HTTP | Code | Meaning |
|---|
| 500 | DB_SAVE_FAILED | The voice was created but couldn't be saved. Contact support with the returned reference. |
| 500 | INTERNAL_ERROR | An unexpected server error. Retry, then contact support. |