Docs · Errors
Every error response from the SonicVox API uses a consistent envelope. Here's what each code means and how to recover.
Seeing 5xx or service_unavailable across the board? Check live service status first — it tells you whether it's us or your account.
Every non-2xx response has this structure:
{
"error": {
"type": "invalid_request_error", // category — branch on this for retry policy
"code": "validation_error", // specific code (see below)
"message": "text: String must contain at most 50000 character(s)",
"status": 422, // mirrors the HTTP status
"request_id": "9f1c2e40-3b7a-4d18-9a55-1c0e2f7b6a31",
"doc_url": "https://staging.sonicvox.ai/docs/errors/validation_error"
}
}The X-Request-Id header is also set on every response — capture it on errors so we can trace any 5xx in our logs.
validation_errorHTTP 422A request parameter failed validation.
The error.message + error.param fields tell you exactly which parameter failed and the valid range. Fix the value and retry — validation errors are not retryable as-is.
invalid_requestHTTP 400The request was malformed or semantically invalid.
Check the error.message and correct the request before retrying.
invalid_inputHTTP 400An input value was rejected before processing began.
Fix the flagged input and retry.
invalid_bodyHTTP 400The request body did not match the schema this endpoint expects.
Send the documented body shape. The error.message states the expected schema.
text_requiredHTTP 400A 'text' field is required — the cloned voice speaks this text.
Send a non-empty 'text' field alongside the reference audio and retry.
invalid_jsonHTTP 400The request body was not valid JSON.
Serialize the body with a real JSON encoder and send Content-Type: application/json.
reference_requiredHTTP 400A reference audio clip was required but not provided.
Attach the required reference clip (see the endpoint's docs) and retry.
reference_invalidHTTP 400The supplied reference audio clip could not be used.
Provide a clean reference clip (a few seconds of clear speech) and retry.
unsupported_output_formatHTTP 400The requested output_format could not be produced.
Request output_format: "wav" (always available) or one of the documented formats. Nothing is charged when this is returned.
unsupported_mediaHTTP 415The uploaded file is not a supported audio/video type.
Upload a standard audio (WAV/MP3/M4A) or video (MP4) file and retry.
file_too_largeHTTP 413The uploaded file exceeded the size cap.
Split or compress the input (use the split tool first) and retry. 200 MB is the hard ceiling for bytes sent through the API.
consent_requiredHTTP 400Voice-cloning consent was not provided.
Include the consent confirmation the endpoint requires, then retry.
invalid_test_typeHTTP 400An unrecognized test/diagnostic type was requested.
Use one of the documented test types and retry.
not_foundHTTP 404The requested resource does not exist.
Verify the id and that your key's account owns the resource.
voice_not_foundHTTP 404The requested voice id does not exist or isn't accessible.
List available voices and use a valid voice_id.
workflow_not_foundHTTP 404No workflow with that id exists on this account.
List your workflows and use an id your key's account owns.
workflow_emptyHTTP 400The workflow exists but has no nodes, so there is nothing to run.
Add at least one node in the workflow editor, then start the run again.
unknown_inputHTTP 400An input key in the request does not match any fillable input of the workflow.
The error.message lists every fillable input id for that workflow — use one of those keys.
run_not_foundHTTP 404No such run for that workflow on this account.
Poll with the run id returned by the run-create call on the same workflow.
missing_api_keyHTTP 401No API key was supplied.
Send your key in the Authorization header on every request.
invalid_api_keyHTTP 401The API key header is missing, malformed, or unknown.
Regenerate the key in /app/admin/api-keys and update your environment. Never commit keys to source control.
insufficient_scopeHTTP 403The API key lacks a scope required by this endpoint.
Mint a key with the needed scope (see each endpoint's required scope) and retry.
account_key_not_agent_scopedHTTP 403An account-level key was used on an agent-scoped endpoint.
Use an agent-bound key for agent-scoped operations.
agent_scope_mismatchHTTP 403An agent-bound key was used against a different agent.
Use the key minted for the agent you're addressing.
plan_requiredHTTP 403Your plan does not include this endpoint or feature.
Upgrade your plan to access this endpoint.
plan_limit_exceededHTTP 403The request is not allowed under your current plan's limits.
The error.message explains the limit. Upgrade your plan or reduce usage.
content_policyHTTP 403The request was blocked by content / voice-safety policy.
Adjust the input to comply with the content policy and retry.
impersonation_blockedHTTP 400The reference clip was blocked by the anti-impersonation gate.
Use a reference clip you have the right to clone.
voice_not_availableHTTP 403The voice exists but cannot currently be synthesized.
This is NOT an auth failure — do not rotate your key. Pick a different voice_id, or wait for the voice to clear review (the message says which state it is in).
ip_blockedHTTP 403The request originated from a blocked IP address.
Contact support@sonicvox.ai if you believe this is a mistake.
insufficient_creditsHTTP 402You don't have enough credits to complete this request.
Top up credits (or enable Auto Top-Up) in billing, then retry. This is NOT retryable until the balance is restored.
daily_limit_exceededHTTP 429You hit your plan's daily usage cap for this operation.
Retry after the daily window resets, or upgrade your plan for a higher cap.
rate_limitHTTP 429You exceeded the per-API-key rate limit for this endpoint.
Retry after the Retry-After header value (seconds). Implement exponential backoff. Some handlers emit this same condition as rate_limited or rate_limit_exceeded — treat all three identically.
rate_limitedHTTP 429Alias of rate_limit emitted by some handlers — same meaning.
Back off per the Retry-After header and retry.
rate_limit_exceededHTTP 429Alias of rate_limit emitted by some handlers — same meaning.
Back off per the Retry-After header and retry.
transcription_failedHTTP 502The transcription / ASR step failed upstream.
Retry with a clean input; if it persists, contact support with the request_id.
enhancement_failedHTTP 502An audio enhancement / effect step failed upstream.
Retry; if it persists, contact support with the request_id.
clone_errorHTTP 502The voice-cloning worker returned an error.
Retry with a valid reference; if it persists, contact support with the request_id.
tts_errorHTTP 502The text-to-speech worker returned an error.
Retry; if it persists, contact support with the request_id.
voice_service_errorHTTP 502A voice service call failed upstream.
Retry; if it persists, contact support with the request_id.
worker_errorHTTP 502A generic processing worker returned an error.
Retry with exponential backoff; if it persists, contact support with the request_id.
unknown_endpointHTTP 404The requested path is not an endpoint of this API.
Check the API reference for the exact path. Note that paths are case-sensitive and have no trailing slash.
tts_request_rejectedHTTP 422The synthesis engine could not process this request.
Check GET /api/v1/models for the languages and capabilities of each engine. Retrying unchanged will not help — nothing was charged.
clone_request_rejectedHTTP 422The cloning engine could not use this reference clip.
Send a clean 3–60s recording of a single speaker. Retrying the same clip will not help.
voice_not_permittedHTTP 403You may not convert into the requested target voice.
Use a voice you own or one from the public library. GET /api/v1/voices lists every voice this key may use.
workflows_unavailableHTTP 403Workflows is not enabled for this account.
Contact support to be enabled. The endpoints stay published so the contract is stable when access is granted.
conversion_failedHTTP 502A Voice Changer job could not be staged or queued.
Retry with exponential backoff. No credits are charged for a job that never queued.
generation_failedHTTP 502A sound-generation job could not be queued.
Retry with exponential backoff. No credits are charged for a job that never queued.
request_timeoutHTTP 408The upload took too long to receive, so no transcription was attempted.
Retry with a smaller file. Nothing was charged — the timeout fires before any engine work begins.
transcription_timeoutHTTP 504Transcription exceeded the synchronous budget.
Split the audio into shorter segments, or retry when load is lower. Reserved credits are settled to the work actually done.
provider_errorHTTP 502An upstream provider returned an error.
Retry with exponential backoff; if it persists, contact support with the request_id.
service_errorHTTP 502A supporting service call failed (e.g. storing the reference audio for a clone).
Retry the request; if it persists, contact support with the request_id.
service_unavailableHTTP 503The service is temporarily unavailable.
Retry after a short delay with exponential backoff.
connection_errorHTTP 503Could not reach an upstream dependency.
Retry after a short delay; if it persists, contact support with the request_id.
endpoint_disabledHTTP 503This endpoint is currently disabled.
Check the status page at /status; retry later or contact support.
internal_errorHTTP 500Unexpected server error.
Retry with exponential backoff. If it persists, capture the request_id and email support@sonicvox.ai — we can trace every 5xx via that ID.
server_errorHTTP 500Unexpected server error (alias of internal_error).
Retry with exponential backoff; include the request_id when contacting support.