Vaakini docs

Reference

Errors

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

View as Markdown

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:

ClientAn API error becomes
Python SDKA vaakini.APIError subclass per code, with code, message, status_code and retryable
LiveKit pluginLiveKit’s APIStatusError, with retryable
Pipecat serviceAn ErrorFrame with the code’s ErrorCategory
Python
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.