Wixzel Voice API errors: types, codes and request ids - Wixzel Voice

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_model",
    "message": "No pricing for deepgram/imaginary-v9. Available for stt: deepgram/nova-3, …",
    "param": "voice",
    "request_id": "req_01HXYZ"
  }
}

Match on code. The message is written for humans and may be reworded for clarity without that being a breaking change.

Every response, success or failure, carries a request_id. Quote it if you need help; it is the fastest way to find what happened.

Types

Type	Meaning
`invalid_request_error`	Something about the request was wrong
`authentication_error`	Missing, malformed, revoked or expired key
`permission_error`	Key lacks the scope for this endpoint
`rate_limit_error`	Too many requests. Not charged
`insufficient_credits`	Not enough balance to place the call
`not_found_error`	No such record, or it belongs to another account
`conflict_error`	The request conflicts with current state
`api_error`	Something failed on our side

Notable codes

Code	What to do
`unsupported_model`	The message lists what IS available for that component
`missing_idempotency_key`	Send a unique value per attempt, such as a UUID
`idempotency_key_reuse`	Same key, different body. Use a new key
`insufficient_credits`	Top up. `X-Wixzel-Balance` carries the current figure
`scope_escalation`	A key cannot grant scopes it does not hold
`engine_unavailable`	Our outage, not your configuration. Retry or pick another engine

Not found means not yours

A record belonging to another account returns 404, not 403. Confirming that something exists but is not yours is itself a disclosure, and would let an attacker enumerate ids.

Rate limits

Exceeding the request-rate limit returns 429 with a Retry-After header. Those requests are never charged: being billed for requests we declined to serve would be indefensible. Provider-backed work is not rate limited by request count. Credits are the control there.