> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Match on code, not message.

```json theme={null}
{
  "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"
  }
}
```

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

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.