Errors and retries
What each status means and what to do about it.
Errors are JSON with a detail field. Rely on the status and retry headers;
keep detail for logs and user-facing hints.
| Status | Meaning | What to do |
|---|---|---|
400 | Invalid input, unknown engine, or bad routing | Fix the request or pick an available engine |
401 | Missing or wrong PIN or API key | Send the credential |
403 | The caller can't use a local or admin route | Use loopback or an allowed route |
409 | A required model or state is missing | Install the recommended model, or resolve the conflict |
422 | The body failed validation | Fix field names, types or ranges |
429 | The GPU queue is full | Wait for Retry-After, then retry |
500 | Unexpected engine or server failure | Log detail; retry only if it is safe |
503 | Engine loading or generation is briefly unavailable | Honor Retry-After |
504 | A guarded transcription or generation timed out | Retry once; shorten the work if it repeats |
Retrying
Retry 429, retryable 503 and 504 with bounded exponential backoff.
VoiceStudio may send:
Retry-After: 30
X-OmniVoice-Retryable: trueDon't retry 400, 401, 403 or 422 automatically. A 409 needs a model
install or another explicit change first.
For dubbing and batch jobs, resume from the job's status after a dropped connection instead of uploading the media again.