Errors
Error codes
Every failure is application/problem+json with a stable code string. Switch on code — never on the prose, and never on the status alone, since 401 covers two different situations.
{
"type": "https://docs.vocalix.ai/errors/insufficient_credit",
"title": "Wallet balance is too low for this request.",
"status": 402,
"code": "insufficient_credit",
"detail": "Wallet has 0 micros available; this request reserves 105.",
"available_micros": 0,
"required_micros": 105
}| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request errors — per-field detail. supported — on an unusable output_format. | The request was malformed. |
| 401 | not_authenticated | No credential was presented. |
| 401 | authentication_failed | The API key is missing, malformed, or not valid. |
| 402 | insufficient_credit available_micros · required_micros | Wallet balance is too low for this request. |
| 403 | permission_denied role · required | This key does not have the required scope. |
| 404 | not_found Echoes the offending identifier, e.g. voice_id. | No such resource. |
| 410 | model_retired migrate_to — never a silent redirect. | This model version has been retired. |
| 429 | rate_limited | Too many requests. |
Two rules worth relying on. Out-of-range speed and pitch are rejected, not clamped — a silently altered parameter is a support ticket nobody can reproduce. And a retired model returns 410 with a migration path rather than quietly serving a newer one, because a silent substitution changes your production output with no signal.