Core concepts

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"
  }
}
FieldDescription
codeStable identifier. Branch on this, not on message. New codes may be added over time.
messageShort English description for logs. It may change; do not show it to end users as-is.
detailsExtra context that depends on the code (for example which fields failed validation). Can be an empty object.
request_idIdentifier 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

StatusWhat to do
400, 404, 413, 415, 422Fix the request. Retrying the same request will fail again.
401, 403Check the key and the role of its creator. See Authentication.
402Not enough credits. Top up in the studio, or estimate first with a quote endpoint. See Credits.
409Conflict with the current state (for example a job that can no longer be canceled). Read the code.
429Slow down. Wait for the number of seconds in Retry-After, then retry. See Rate limits.
500, 502, 503, 504Retry with exponential backoff. Use an Idempotency-Key so retries never create duplicate jobs.

Common codes

CodeStatusMeaning
validation_failed400The request does not match the schema; see details.issues.
validation_unknown_field400The body contains a field the endpoint does not accept.
validation_webhook_url400webhook_url must be a public https address.
auth_api_key_invalid401The API key is wrong or revoked.
wallet_insufficient_credits402The account does not have enough credits for this job.
job_not_found404No job with this id in your account.
asset_not_found404No file with this id in your account.
job_idempotency_conflict409The Idempotency-Key was already used with a different request.
job_not_cancelable409The job already finished.
quota_rate_limited429Too many requests for this key; see Retry-After.
job_concurrency_limit429Too many jobs running at once; wait for some to finish.
system_error500Unexpected 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

CodeHTTPMessage
validation_failed400Request validation failed
validation_unknown_field400Unknown field in request
validation_bad_cursor400Invalid pagination cursor
validation_payload_too_large413Request body is too large
validation_method_not_allowed405HTTP method is not allowed on this endpoint
validation_webhook_url400Webhook URL must be a public https address

Authentication & permissions

CodeHTTPMessage
auth_required401Authentication required
auth_forbidden403Not allowed
auth_api_key_invalid401Invalid API key

Account

CodeHTTPMessage
account_role_required403Your role does not allow this action
account_api_key_not_found404API key not found
account_api_key_limit409API key limit reached

Credits

CodeHTTPMessage
wallet_insufficient_credits402Insufficient credits
wallet_hold_not_found404Hold not found
wallet_already_settled409Hold is already settled
wallet_invalid_amount400Amount must be a positive integer
wallet_rate_missing500Credit rate is not defined
wallet_ref_conflict409Reference is already used by another account

Jobs

CodeHTTPMessage
job_not_found404Job not found
job_studio_unknown400Unknown studio
job_kind_unknown400Unknown job kind for this studio
job_input_invalid400Job input is invalid
job_not_cancelable409Job can no longer be canceled
job_concurrency_limit429Too many jobs running at once
job_idempotency_conflict409Idempotency key was used with a different request
job_failed500Job failed
job_canceled409Job was canceled
job_studio_disabled404Studio is not enabled
job_still_running409Job is still running
job_stalled500Job stopped responding
job_url_not_allowed400This address cannot be accessed
job_url_unreachable422The link could not be read
job_image_too_large413Image is too large for this generation

Files

CodeHTTPMessage
asset_not_found404Asset not found
asset_too_large413File is larger than the limit
asset_too_long400Media is longer than the limit
asset_type_not_allowed415File type is not allowed
asset_type_mismatch415File content does not match the declared type
asset_upload_incomplete409Upload is not complete
asset_upload_expired410Upload session expired
asset_not_ready409Asset is not ready
asset_url_invalid403Signed address is invalid
asset_url_expired403Signed address expired
asset_range_invalid416Upload range is invalid
asset_in_use409Asset is used by a running job
asset_empty400File is empty
asset_corrupt422File is damaged or cannot be read
asset_no_audio_track422Media has no audio track
asset_silent422No speech was detected in the media
asset_too_short422Media is too short

Quotas & rate limits

CodeHTTPMessage
quota_rate_limited429Too many requests
quota_guest_exceeded429Free usage limit reached; sign up to continue
quota_daily_exceeded429Daily limit reached
quota_monthly_exceeded429Monthly limit reached
quota_verification_required403Human verification required
quota_verification_failed403Human verification failed
quota_guest_not_allowed403Sign in to use this feature
quota_storage_exceeded413Storage limit reached

Generation

CodeHTTPMessage
provider_rejected422Provider rejected the content
provider_unavailable503Provider is unavailable
provider_clone_unavailable503Cloned voice cannot be synthesized right now
provider_timeout504Provider timed out
provider_quota503Provider quota reached
provider_budget_exceeded503Daily provider budget reached
provider_incomplete502Provider returned an incomplete result

Studio

CodeHTTPMessage
studio_record_locked409Record is locked
studio_version_conflict409Record was changed; reload and try again
studio_limit_exceeded413Studio record limit reached

Documents

CodeHTTPMessage
document_ocr_required422Document has no text layer; OCR is required
document_unreadable422Document could not be read

General

CodeHTTPMessage
not_found404Not found
system_error500Internal error