# Errors

> The one error shape, every code, and how each client reports them.

## The shape

Every error, on every route, has a code, a message and retryable.

```http
HTTP/1.1 400 Bad Request
content-type: application/json

{"error":{"code":"bad_request","message":"invalid request: speed: vaakini-tts-1 takes no speed","retryable":false}}
```

`code` is one of the codes below: branch on it. `message` is for people, and its wording can change. `retryable` says whether the same request may succeed if sent again.

## Codes

- `bad_request` (HTTP 400 (422 on /v1/custom-voices), not retryable): The request failed validation, or a WebSocket message arrived out of order. The message names the field or the rule.
- `unauthorized` (HTTP 401, not retryable): The API key is missing, wrong or deleted.
- `insufficient_credits` (HTTP 402, not retryable): Your org is out of credit, so new connections and requests are refused until it has credit again ([Billing](https://app.vaakini.com/app/billing)). Connections already open carry on.
- `not_found` (HTTP 404, not retryable): No such path, or no such custom voice in your org.
- `custom_voices_not_enabled` (HTTP 403, not retryable): [Custom voices](https://docs.vaakini.com/custom-voices.md#enable) aren’t enabled for your org.
- `custom_voice_limit` (HTTP 409, not retryable): Your org holds as many custom voices as it can. Delete one to make another.
- `rate_limited` (HTTP 429, retryable): The model is at capacity. Try again in a moment.
- `unavailable` (HTTP 502 (503 on /v1/custom-voices), retryable): The model is unavailable, or the connection to it failed.
- `timeout` (HTTP 504, retryable): The model sent no audio in time.
- `internal` (HTTP 500, retryable): The request failed on our side.

## How each surface reports them

**HTTP.** The JSON body above, with the code’s status. On `/v1/audio/speech` the status is sent with the first audio, so an error after audio has started can only abort the body: the response ends early, which HTTP clients raise as an error. Treat that request as failed.

**WebSocket (`/v1/stream`).** An `error` message with the same three fields ends the segment, and Vaakini then closes the connection. `segment_id` is null when no segment was open. A wrong key and an org out of credit are refused before the connection opens, as HTTP 401 and 402 at the handshake.

```json
{"type": "error", "segment_id": "reply-1", "code": "rate_limited", "message": "vaakini-tts-1 is at capacity, try again", "retryable": true}
```

**The clients.** Each turns an error into its framework’s own kind:

| Client | An API error becomes |
| --- | --- |
| [Python SDK](https://docs.vaakini.com/python.md#errors) | A `vaakini.APIError` subclass per code, with `code`, `message`, `status_code` and `retryable` |
| [LiveKit plugin](https://docs.vaakini.com/livekit.md#errors) | LiveKit’s `APIStatusError`, with `retryable` |
| [Pipecat service](https://docs.vaakini.com/pipecat.md#errors) | An `ErrorFrame` with the code’s `ErrorCategory` |

```python
import vaakini
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

try:
    client.speech.create(input="नमस्ते।", voice="NoSuchVoice")
except vaakini.APIError as e:
    print(type(e).__name__, e.code, e.status_code, e.retryable)
    print(e.message)
except vaakini.APIConnectionError:
    print("the API could not be reached, or the audio ended early")
```

## Retrying

Retry only when `retryable` is true (`rate_limited`, `unavailable`, `timeout`, `internal`), after a short pause, and on the WebSocket on a new connection. The others need a change first: a corrected request, a valid key, or credit.

A reply that failed partway may already have played some sentences. Sending it again speaks it from the start.
