Reference
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/1.1 400 Bad Requestcontent-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_requestHTTP 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.
unauthorizedHTTP 401, not retryable- The API key is missing, wrong or deleted.
insufficient_creditsHTTP 402, not retryable- Your org is out of credit, so new connections and requests are refused until it has credit again (Billing). Connections already open carry on.
not_foundHTTP 404, not retryable- No such path, or no such custom voice in your org.
custom_voices_not_enabledHTTP 403, not retryable- Custom voices aren’t enabled for your org.
custom_voice_limitHTTP 409, not retryable- Your org holds as many custom voices as it can. Delete one to make another.
rate_limitedHTTP 429, retryable- The model is at capacity. Try again in a moment.
unavailableHTTP 502 (503 on /v1/custom-voices), retryable- The model is unavailable, or the connection to it failed.
timeoutHTTP 504, retryable- The model sent no audio in time.
internalHTTP 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.
{"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 | A vaakini.APIError subclass per code, with code, message, status_code and retryable |
| LiveKit plugin | LiveKit’s APIStatusError, with retryable |
| Pipecat service | An ErrorFrame with the code’s ErrorCategory |
import vaakinifrom vaakini import Vaakiniclient = Vaakini() # reads VAAKINI_API_KEYtry: 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.