Errors

Kova returns JSON error bodies for every status code except 500, which returns plain text. The HTTP status is the primary signal; the JSON body carries an error or detail field.

Do not assume error bodies are JSON. A 500 returns Content-Type: text/plain with the literal body Internal Server Error. Calling .json() on it will throw. Guard every error parse.

Status code summary

Status	Body	Cause
`401`	`{"error": "Invalid or missing API key"}`	Header missing, or doesn’t start with `kova_sk_`.
`401`	`{"error": "INVALID_API_KEY"}`	Well-formed key that doesn’t exist or was revoked.
`402`	`{"error": "INSUFFICIENT_CREDITS"}`	Account out of credit.
`405`	`{"detail": "Method Not Allowed"}`	Wrong HTTP method on a valid path.
`422`	`{"detail": [ ... ]}`	Request body failed validation.
`429`	`{"error": "Rate limit exceeded", "reason": "concurrency"}`	9 requests already in flight on this key.
`500`	`Internal Server Error` (plain text)	Genuine server fault. Transient — retry with backoff.

The `x-request-id` header

Successful and most failed responses carry an x-request-id header. Log it — it’s what support needs to trace a request.

x-request-id: 77d989199c5a6d965c99f76cab579509

x-request-id is returned on every response, including 500s. Always log it — it’s what support needs to trace a request.

401 Unauthorized

Two distinct shapes, depending on where the request was rejected. Missing or malformed key — rejected at the gateway:

{"error": "Invalid or missing API key"}

Returned when the x-api-key header is absent, or its value doesn’t begin with kova_sk_. Also returned if you send Authorization: Bearer <key> instead — Kova does not accept bearer tokens. Well-formed but unknown key — rejected at the billing service:

{"error": "INVALID_API_KEY"}

The header parsed correctly but the key doesn’t exist or has been revoked. Fix: Verify the header name and value, then regenerate on Dashboard → API keys. The header name is case-insensitive — x-api-key and X-API-KEY both work.

402 Payment Required

{"error": "INSUFFICIENT_CREDITS"}

Cause: The account behind the key has run out of credit. Fix: Top up at Dashboard → Billing. Requests resume as soon as credit lands — the key stays valid, so there’s nothing to regenerate.

422 Unprocessable Entity

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "voice"],
      "msg": "Field required",
      "input": {"text": "hello"}
    }
  ]
}

detail is an array and may contain several errors at once. loc is the path to the offending field.

Common causes and exact messages

Cause	`msg`
Missing `text` or `voice`	`Field required`
Unknown field in the body	`Extra inputs are not permitted`
Wrong type	`Input should be a valid string` / `... valid boolean`
`response_format: null`	`Input should be a valid dictionary or object to extract fields from`
Bad encoding	`Value error, Unsupported audio encoding: flac`
Bad rate for encoding	`Value error, mp3 audio sample_rate must be between 16000 and 48000 Hz`
Bad opus rate	`Value error, opus audio sample_rate must be one of 8000, 12000, 16000, 24000, or 48000 Hz`
Bad telephony rate	`Value error, mulaw audio requires an 8000 Hz sample rate`
Bad bitrate	`Value error, mp3 audio bitrate must be between 32kbps and 320kbps`
Unparseable bitrate	`Value error, Invalid mp3 audio bitrate: abc`
Bitrate on a PCM-family encoding	`Value error, wav audio does not support a bitrate option`
`temperature` below range	`Input should be greater than or equal to 0.5`
`temperature` above range	`Input should be less than or equal to 3`

Two easy 422s to hit: passing bitrate in bits per second (128000) instead of kbps ("128k" or 128), and passing bitrate at all to wav, pcm, linear16, mulaw or alaw. See Text to speech.

Unknown voice

A voice that isn’t in the catalog returns 422 with a different body shape from the validation errors above — no detail array:

{
  "error": "unknown_voice",
  "message": "Unknown voice 'nope'. Valid voices: ash, ash_conv, cal, mira, mira_conv, owen, paul, tess, theo",
  "voice": "nope",
  "valid_voices": ["ash", "ash_conv", "cal", "mira", "mira_conv", "owen", "paul", "tess", "theo"]
}

valid_voices is the live catalog, so this error is self-correcting — you can read the allowed set straight off the failure. The same shape is returned by POST /v1/tts, POST /v1/tts/stream, and the Vapi endpoint.

Because this body has error and not detail, code that assumes every 422 has a detail array will KeyError here. Branch on which key is present.

429 Too Many Requests

{"error": "Rate limit exceeded", "reason": "concurrency"}

Cause: Your key already has 9 requests in flight. The 10th is rejected immediately — nothing queues server-side. HTTP requests and open WebSocket connections draw on the same budget. Fix: Hold a client-side semaphore of 9 or fewer, and retry with backoff.

429 responses carry no Retry-After header. Choose your own schedule — start at 200 ms and back off exponentially with jitter, capped around 5 s.

See Rate limits for the full policy.

500 Internal Server Error

Internal Server Error

Plain text, Content-Type: text/plain; charset=utf-8, with an x-request-id header. A genuine server fault. Transient — retry with backoff. The SDKs retry 5xx automatically.

Note the content type: 500 is the one status code that does not return JSON. Guard your error parsing so a .json() call doesn’t throw on top of the original failure.

For persistent 500s, contact support with the x-request-id.

WebSocket errors

The WebSocket transport does not use HTTP status codes after the handshake. Failures arrive as error frames:

{"error": "unknown context_id: c1", "context_id": "c1"}

Key differences from HTTP:

error frames are not fatal. The socket stays open and other contexts keep working.
An unknown voice_id produces a clean error frame naming every valid voice.
A revoked key produces {"error": "INVALID_API_KEY"} followed by WebSocket close code 1008 (policy violation).
A malformed frame produces {"error": "invalid frame: ..."} with the underlying validation message.

See WebSocket frames for the full frame reference.

How errors surface in the SDKs

from kova_tts import KovaTTSClient, KovaTTSError

client = KovaTTSClient(api_key="kova_sk_...")
try:
    result = client.tts(text="hi", voice="cal")
except KovaTTSError as e:
    print(e.status_code, e.body)  # e.g. 401 {'error': 'Invalid or missing API key'}

import { KovaTTSClient, KovaTTSError } from "@kova-ai/tts";

const client = new KovaTTSClient({ apiKey: "kova_sk_..." });
try {
  await client.tts({ text: "hi", voice: "cal" });
} catch (e) {
  if (e instanceof KovaTTSError) {
    console.log(e.status, e.body);
  }
}

The SDKs also export KovaTTSAuthError (401), KovaTTSRateLimitError (429), KovaTTSValidationError (422), KovaTTSServerError (5xx), KovaTTSConnectionError, and KovaTTSProtocolError. Catch the base KovaTTSError to handle everything; catch subclasses when you need to branch per code.

Get started

HTTP API

WebSocket API

Voices

Integrations

SDKs

Reference

Status code summary

The `x-request-id` header

401 Unauthorized

402 Payment Required

422 Unprocessable Entity

Common causes and exact messages

Unknown voice

429 Too Many Requests

500 Internal Server Error

WebSocket errors

How errors surface in the SDKs

​Status code summary

​The x-request-id header

​401 Unauthorized

​402 Payment Required

​422 Unprocessable Entity

​Common causes and exact messages

​Unknown voice

​429 Too Many Requests

​500 Internal Server Error

​WebSocket errors

​How errors surface in the SDKs

Status code summary

The `x-request-id` header

401 Unauthorized

402 Payment Required

422 Unprocessable Entity

Common causes and exact messages

Unknown voice

429 Too Many Requests

500 Internal Server Error

WebSocket errors

How errors surface in the SDKs