Errors
Every error uses the same JSON shape with a stable, machine-readable code.
Voiser uses conventional HTTP status codes: 2xx means success, 4xx means the request needs to change, and 5xx means something went wrong on our side. Every error response has the same body:
{
"error": {
"code": "wallet_insufficient_credits",
"message": "Insufficient credits",
"details": {},
"request_id": "c1f2e3d4-5b6a-4789-9abc-def012345678"
}
}| Field | Description |
|---|---|
code | Stable identifier. Branch on this, not on message. New codes may be added over time. |
message | Short English description for logs. It may change; do not show it to end users as-is. |
details | Extra context that depends on the code (for example which fields failed validation). Can be an empty object. |
request_id | Identifier of the request (also sent as the X-Request-Id response header). Include it when you contact support. |
Validation errors
When the body or query string does not match the schema, the API returns 400 with validation_failed and lists the problems in details.issues. Each issue has the path of the field and the rule it broke. Unknown fields are rejected with validation_unknown_field so that typos never pass silently.
{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"details": {
"issues": [
{ "path": "body.voice_id", "rule": "invalid_format" },
{ "path": "body.settings.speed", "rule": "too_big" }
]
},
"request_id": "c1f2e3d4-5b6a-4789-9abc-def012345678"
}
}Errors inside jobs
A generation that fails after it was accepted does not turn into an HTTP error: the request that created the job already returned 202. The job's status becomes failed, and its error field holds the same code / message / details structure. Held credits are released. See Jobs.
Handling errors
| Status | What to do |
|---|---|
400, 404, 413, 415, 422 | Fix the request. Retrying the same request will fail again. |
401, 403 | Check the key and the role of its creator. See Authentication. |
402 | Not enough credits. Top up in the studio, or estimate first with a quote endpoint. See Credits. |
409 | Conflict with the current state (for example a job that can no longer be canceled). Read the code. |
429 | Slow down. Wait for the number of seconds in Retry-After, then retry. See Rate limits. |
500, 502, 503, 504 | Retry with exponential backoff. Use an Idempotency-Key so retries never create duplicate jobs. |
Common codes
| Code | Status | Meaning |
|---|---|---|
validation_failed | 400 | The request does not match the schema; see details.issues. |
validation_unknown_field | 400 | The body contains a field the endpoint does not accept. |
validation_webhook_url | 400 | webhook_url must be a public https address. |
auth_api_key_invalid | 401 | The API key is wrong or revoked. |
wallet_insufficient_credits | 402 | The account does not have enough credits for this job. |
job_not_found | 404 | No job with this id in your account. |
asset_not_found | 404 | No file with this id in your account. |
job_idempotency_conflict | 409 | The Idempotency-Key was already used with a different request. |
job_not_cancelable | 409 | The job already finished. |
quota_rate_limited | 429 | Too many requests for this key; see Retry-After. |
job_concurrency_limit | 429 | Too many jobs running at once; wait for some to finish. |
system_error | 500 | Unexpected error. Retry with backoff. |
All error codes
The full catalog below is generated from the API's OpenAPI document. Some codes belong to features of the studio and never occur through the API.
Validation
| Code | HTTP | Message |
|---|---|---|
validation_failed | 400 | Request validation failed |
validation_unknown_field | 400 | Unknown field in request |
validation_bad_cursor | 400 | Invalid pagination cursor |
validation_payload_too_large | 413 | Request body is too large |
validation_method_not_allowed | 405 | HTTP method is not allowed on this endpoint |
validation_webhook_url | 400 | Webhook URL must be a public https address |
Authentication & permissions
| Code | HTTP | Message |
|---|---|---|
auth_required | 401 | Authentication required |
auth_forbidden | 403 | Not allowed |
auth_api_key_invalid | 401 | Invalid API key |
Account
| Code | HTTP | Message |
|---|---|---|
account_role_required | 403 | Your role does not allow this action |
account_api_key_not_found | 404 | API key not found |
account_api_key_limit | 409 | API key limit reached |
Credits
| Code | HTTP | Message |
|---|---|---|
wallet_insufficient_credits | 402 | Insufficient credits |
wallet_hold_not_found | 404 | Hold not found |
wallet_already_settled | 409 | Hold is already settled |
wallet_invalid_amount | 400 | Amount must be a positive integer |
wallet_rate_missing | 500 | Credit rate is not defined |
wallet_ref_conflict | 409 | Reference is already used by another account |
Jobs
| Code | HTTP | Message |
|---|---|---|
job_not_found | 404 | Job not found |
job_studio_unknown | 400 | Unknown studio |
job_kind_unknown | 400 | Unknown job kind for this studio |
job_input_invalid | 400 | Job input is invalid |
job_not_cancelable | 409 | Job can no longer be canceled |
job_concurrency_limit | 429 | Too many jobs running at once |
job_idempotency_conflict | 409 | Idempotency key was used with a different request |
job_failed | 500 | Job failed |
job_canceled | 409 | Job was canceled |
job_studio_disabled | 404 | Studio is not enabled |
job_still_running | 409 | Job is still running |
job_stalled | 500 | Job stopped responding |
job_url_not_allowed | 400 | This address cannot be accessed |
job_url_unreachable | 422 | The link could not be read |
job_image_too_large | 413 | Image is too large for this generation |
Files
| Code | HTTP | Message |
|---|---|---|
asset_not_found | 404 | Asset not found |
asset_too_large | 413 | File is larger than the limit |
asset_too_long | 400 | Media is longer than the limit |
asset_type_not_allowed | 415 | File type is not allowed |
asset_type_mismatch | 415 | File content does not match the declared type |
asset_upload_incomplete | 409 | Upload is not complete |
asset_upload_expired | 410 | Upload session expired |
asset_not_ready | 409 | Asset is not ready |
asset_url_invalid | 403 | Signed address is invalid |
asset_url_expired | 403 | Signed address expired |
asset_range_invalid | 416 | Upload range is invalid |
asset_in_use | 409 | Asset is used by a running job |
asset_empty | 400 | File is empty |
asset_corrupt | 422 | File is damaged or cannot be read |
asset_no_audio_track | 422 | Media has no audio track |
asset_silent | 422 | No speech was detected in the media |
asset_too_short | 422 | Media is too short |
Quotas & rate limits
| Code | HTTP | Message |
|---|---|---|
quota_rate_limited | 429 | Too many requests |
quota_guest_exceeded | 429 | Free usage limit reached; sign up to continue |
quota_daily_exceeded | 429 | Daily limit reached |
quota_monthly_exceeded | 429 | Monthly limit reached |
quota_verification_required | 403 | Human verification required |
quota_verification_failed | 403 | Human verification failed |
quota_guest_not_allowed | 403 | Sign in to use this feature |
quota_storage_exceeded | 413 | Storage limit reached |
Generation
| Code | HTTP | Message |
|---|---|---|
provider_rejected | 422 | Provider rejected the content |
provider_unavailable | 503 | Provider is unavailable |
provider_clone_unavailable | 503 | Cloned voice cannot be synthesized right now |
provider_timeout | 504 | Provider timed out |
provider_quota | 503 | Provider quota reached |
provider_budget_exceeded | 503 | Daily provider budget reached |
provider_incomplete | 502 | Provider returned an incomplete result |
Studio
| Code | HTTP | Message |
|---|---|---|
studio_record_locked | 409 | Record is locked |
studio_version_conflict | 409 | Record was changed; reload and try again |
studio_limit_exceeded | 413 | Studio record limit reached |
Documents
| Code | HTTP | Message |
|---|---|---|
document_ocr_required | 422 | Document has no text layer; OCR is required |
document_unreadable | 422 | Document could not be read |
General
| Code | HTTP | Message |
|---|---|---|
not_found | 404 | Not found |
system_error | 500 | Internal error |