Errors

The API returns errors as JSON. The HTTP TTS endpoints (/tts/bytes, /tts/sse) use a four-field envelope; /voices/clone uses two shorter shapes (see Voice cloning errors).

Error Format

{
  "error": "voice_not_found",
  "error_code": "voice_not_found",
  "message": "voice not found",
  "detail": "voice not found"
}

Field	Type	Description
`error_code`	string	Canonical machine-readable error code — key on this
`error`	string	Mirrors `error_code`
`message`	string	Human-readable description
`detail`	string	Backward-compatible detail string; usually mirrors `message`

/voices/clone returns { "detail": "..." } for audio validation errors and { "error": "...", "message": "..." } for everything else. WebSocket errors arrive as a Cartesia-shaped error frame with error_code, status_code, context_id, and done: true.

Error Code Reference

`error_code`	Status	Endpoints	Meaning
`missing_transcript`	400	bytes · sse · ws	`transcript` empty, whitespace-only, or (WS) omitted
`missing_voice`	400	bytes · sse · ws	`voice` missing, not an object, or empty
`missing_voice_id`	400	bytes · sse · ws	`voice.mode` is `id` but `voice.id` missing/empty
`unknown_voice_mode`	400	bytes · sse · ws	`voice.mode` is not `id`
`input_too_long`	400	bytes · sse · ws	`transcript` is over 2,000 characters (per request, or per WebSocket message)
`voice_not_found`	404	bytes · sse · ws	`voice.id` not found (or owned by another org)
`payload_too_large`	413	bytes · sse	Request body exceeds 64 KB (65536 bytes)
`unknown_model`	400	bytes · sse · ws	`model_id` is not a supported model
`overloaded`	429	bytes · sse · ws	The synthesis servers are at capacity. Retry with backoff
`engine_error`	502 (or 4xx)	bytes · sse · ws	Generation failed. Retry
`engine_unavailable`	503	bytes · sse · ws	The synthesis engine is temporarily unavailable. Retry shortly
`missing_context_id`	400	ws	A cancel was sent without `context_id` (`?cancel_ack=true` connections only)
`context_not_found`	404	ws	A cancel targeted a context that isn’t active (`?cancel_ack=true` connections only)
`invalid_language`	400	voices/clone	`language` is not a well-formed BCP-47 tag
`clone_failed`	502	voices/clone	The voice couldn’t be created. Retry
`db_unavailable`	503	voices/clone	Voice storage is temporarily unavailable. Retry shortly

`unauthorized` (401)

The API key is missing, malformed, invalid, or revoked.

{ "error": "unauthorized", "message": "invalid API key" }

Fix: Send a valid, non-revoked key via Authorization: Bearer sk_996_... (or ?api_key= for WebSockets).

`missing_transcript` (400)

The transcript is empty, whitespace-only, or (on WebSocket) omitted. On the WebSocket a message that omits transcript returns this error frame and the socket closes — but an empty string with continue: false is the valid end-of-turn flush marker, not an error.

{ "error": "missing_transcript", "error_code": "missing_transcript", "message": "transcript is required", "detail": "transcript is required" }

`missing_voice` / `missing_voice_id` / `unknown_voice_mode` (400)

The voice field is required and must be the nested object { "mode": "id", "id": "<voice-id>" }. There is no default voice — a request that doesn’t resolve to a voice is rejected (it is no longer silently substituted). A top-level voice_id is not supported. On the WebSocket these arrive as an error frame and the socket closes.

`error_code`	Condition
`missing_voice`	`voice` missing, not an object, or empty
`missing_voice_id`	`voice.mode` is `id` but `voice.id` missing/empty
`unknown_voice_mode`	`voice.mode` is not `id` (the only supported mode)

{ "error": "missing_voice", "error_code": "missing_voice", "message": "voice is required", "detail": "voice is required" }

`voice_not_found` (404)

The voice.id doesn’t exist or belongs to another organization.

{ "error": "voice_not_found", "error_code": "voice_not_found", "message": "voice not found", "detail": "voice not found" }

Fix: List available voices with GET /voices and pass an id your org owns.

`input_too_long` (400)

transcript is longer than 2,000 characters. The limit applies per /tts/bytes or /tts/sse request and per WebSocket message. Characters are counted the same way as for billing — Unicode code points of the string as sent, including leading and trailing whitespace and newlines — so you can check before sending (len(text) in Python, [...text].length in JavaScript; see Length limit). The check runs before any work starts, so nothing is billed. On /tts/bytes and /tts/sse it’s an HTTP 400 (on SSE, before the event stream opens):

{ "error": "input_too_long", "error_code": "input_too_long", "message": "transcript is 2345 characters; the maximum is 2000 per request — split longer text across requests or WebSocket messages", "detail": "transcript is 2345 characters; the maximum is 2000 per request — split longer text across requests or WebSocket messages" }

On the WebSocket it’s an error frame for that context (error_code: "input_too_long", status_code: 400). The over-long message isn’t synthesized or billed, and the socket and your other contexts carry on. If that message would have ended a turn already in progress, the turn still completes with its earlier sentences and sends done. Fix: Split longer text across multiple requests, or send it over the WebSocket as several messages with continue: true.

`payload_too_large` (413)

On /tts/bytes and /tts/sse, the request body exceeds the 64 KB (65536-byte) cap. Normal requests are nowhere near this — it’s a safety limit. Uses the shorter { error, message } shape.

{ "error": "payload_too_large", "message": "request body exceeds 65536 bytes" }

`unknown_model` (400)

The model_id is not a supported model. Send gepard-1.0.

`invalid_language` (400)

On POST /voices/clone, the language form field is not a well-formed BCP-47 tag. Send the full dialect (e.g. en-US, en-GB, es-MX, pt-BR, nl-NL); malformed tags (en_US, en-USA, english_, 123) are rejected. The value is canonicalized on save (en-us → en-US). Uses the { error, message } shape.

{ "error": "invalid_language", "message": "language must be a BCP-47 tag like \"en-US\"; got \"en_US\"" }

Voice cloning errors

POST /voices/clone returns errors in two shapes. Audio validation errors use { "detail": "..." }:

Status	Condition	`detail`
400	The clip can’t be decoded	`Bad clip (expected WAV): could not decode audio: <decoder message>` — says “WAV” even when you uploaded another supported format
400	The clip is shorter than 1 second	`Bad clip: reference audio is 0.62s; need at least 1 s`
413	The clip is longer than 300 seconds	`Bad clip: reference audio is 312.4s; max 300s`
413	The upload is over 20 MB	`clip exceeds 20 MB`
503	The cloning service is still starting. Retry shortly	`TTS models not initialized`

{ "detail": "Bad clip: reference audio is 0.62s; need at least 1 s" }

Other errors use { "error": "...", "message": "..." }:

`error`	Status	Condition
`invalid_language`	400	`language` is not a well-formed BCP-47 tag (see above)
`clone_failed`	502	The voice couldn’t be created. Retry
`db_unavailable`	503	Voice storage is temporarily unavailable. Retry shortly

To handle both, read error if it’s present and fall back to detail.

Invalid or malformed body (400)

The request body isn’t valid JSON, or a required field (model_id, transcript, voice, output_format) is missing.

Invalid `output_format` (400)

The output_format uses an unsupported container, encoding, or sample_rate. Validation is strict — there’s no silent fallback. The message names the offending field. Common causes:

Removed formats: container: "mp3", encoding: "pcm_f32le"
Unsupported sample_rate (only 8000, 16000, 22050, 24000, 44100, 48000 are allowed)
container: "wav" on a streaming endpoint (/tts/sse, /tts/websocket are raw-only)

Fix: Use a supported combination — see Create Speech → Output Format.

`payment_required` (402)

The organization’s balance is zero or below. Billing is postpaid: new requests start only while the balance is positive, so the last request before you run out can take it slightly below zero. On the WebSocket this arrives as an insufficient_credits (402) frame and the socket closes — including mid-stream, if the balance reaches zero while you’re streaming.

{ "error": "payment_required", "message": "insufficient credits" }

Fix: Top up on the Billing page.

`rate_limited` / `concurrent_limit` (429)

You’ve exceeded your org’s per-minute request rate or concurrency cap (shared across all your API keys). See Rate Limits. Fix: Honor the Retry-After header and retry. For concurrent_limit, retry the rejected turn on a fresh context_id — only that context was rejected, not the whole connection.

`overloaded` (429)

The synthesis servers are at capacity. This is separate from your tier’s concurrent_limit: it can happen even when you’re well under your own limits.

{ "error": "overloaded", "error_code": "overloaded", "message": "too many active streams; retry later", "detail": "too many active streams; retry later" }

Fix: Retry with exponential backoff. Don’t rely on a Retry-After header for this error.

`engine_error` (502) / `engine_unavailable` (503)

engine_error means generation failed; engine_unavailable means the synthesis engine is temporarily unavailable. For both, the message is passed through from the engine and varies (for example, All connection attempts failed for engine_unavailable), so don’t match on it. engine_error is usually 502, but it can carry a 4xx status passed through from the engine. Key on error_code, not the HTTP status.

{ "error": "engine_unavailable", "error_code": "engine_unavailable", "message": "All connection attempts failed", "detail": "All connection attempts failed" }

Fix: Retry the request. For engine_unavailable, wait a moment first.

Generation errors by endpoint

overloaded, engine_error, and engine_unavailable arrive differently depending on the endpoint:

/tts/bytes — a normal HTTP error with the four-field envelope above. /tts/bytes is all-or-nothing, so a failed request returns no audio and isn’t charged.
/tts/sse — either a normal HTTP error before the stream opens, or mid-stream as an error event inside the HTTP 200 response. The stream ends after the error event, with no done, so handle error events as well as chunk and done. If at least one audio chunk was delivered before the error, the request is charged for the full transcript.
data: {"type": "error", "context_id": "<context_id>", "done": true, "error_code": "overloaded", "status_code": 429, "title": "Overloaded", "message": "too many active streams; retry later", "doc_url": "", "request_id": "<request_id>"}
/tts/websocket — an error frame for the affected context. The socket stays open; that context’s queued sentences are dropped and other contexts keep running. Text not yet billed for that turn isn’t charged; 1,000-character batches already billed stay charged. Retry the turn on a fresh context_id.

`missing_context_id` (400) / `context_not_found` (404)

WebSocket only, and only on connections opened with ?cancel_ack=true. A cancel without a context_id returns missing_context_id; a cancel for a context that isn’t active (unknown, already finished, or already cancelled) returns context_not_found. Both arrive as error frames and the socket stays open. If a cancel races a context that finishes on its own, you’ll get the normal done followed by context_not_found — safe to ignore. See WebSocket Streaming.

`billing_unavailable` (503)

Credits couldn’t be verified, so the request fails closed (no audio is generated and you aren’t charged). Fix: Retry shortly.

`upstream_unavailable` (502)

The synthesis backend errored. Failed requests aren’t charged. Fix: Retry the request. If it persists, contact support.

Handling Errors in Code

import { Cartesia, APIError } from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: "sk_996_your_api_key", baseURL: "https://api.nineninesix.ai" });

try {
  const res = await client.tts.generate({
    model_id: "gepard-1.0",
    transcript: "Hello!",
    voice: { mode: "id", id: "<voice-id>" },
    output_format: { container: "wav", encoding: "pcm_s16le", sample_rate: 22050 },
  });
} catch (err) {
  if (err instanceof APIError) {
    if (err.status === 402) console.error("Out of credits — top up");
    else if (err.status === 429) console.error("Rate limited or overloaded — back off and retry");
    else if (err.status === 502 || err.status === 503) console.error("Engine error — retry");
    else console.error(`API error: ${err.message}`);
  }
}

Getting Started

Guides

Resources

Errors

Error Format

Error Code Reference

Errors

`unauthorized` (401)

`missing_transcript` (400)

`missing_voice` / `missing_voice_id` / `unknown_voice_mode` (400)

`voice_not_found` (404)

`input_too_long` (400)

`payload_too_large` (413)

`unknown_model` (400)

`invalid_language` (400)

Voice cloning errors

Invalid or malformed body (400)

Invalid `output_format` (400)

`payment_required` (402)

`rate_limited` / `concurrent_limit` (429)

`overloaded` (429)

`engine_error` (502) / `engine_unavailable` (503)

Generation errors by endpoint

`missing_context_id` (400) / `context_not_found` (404)

`billing_unavailable` (503)

`upstream_unavailable` (502)

Handling Errors in Code

​Error Format

​Error Code Reference

​Errors

​unauthorized (401)

​missing_transcript (400)

​missing_voice / missing_voice_id / unknown_voice_mode (400)

​voice_not_found (404)

​input_too_long (400)

​payload_too_large (413)

​unknown_model (400)

​invalid_language (400)

​Voice cloning errors

​Invalid or malformed body (400)

​Invalid output_format (400)

​payment_required (402)

​rate_limited / concurrent_limit (429)

​overloaded (429)

​engine_error (502) / engine_unavailable (503)

​Generation errors by endpoint

​missing_context_id (400) / context_not_found (404)

​billing_unavailable (503)

​upstream_unavailable (502)

​Handling Errors in Code

Error Format

Error Code Reference

Errors

`unauthorized` (401)

`missing_transcript` (400)

`missing_voice` / `missing_voice_id` / `unknown_voice_mode` (400)

`voice_not_found` (404)

`input_too_long` (400)

`payload_too_large` (413)

`unknown_model` (400)

`invalid_language` (400)

Voice cloning errors

Invalid or malformed body (400)

Invalid `output_format` (400)

`payment_required` (402)

`rate_limited` / `concurrent_limit` (429)

`overloaded` (429)

`engine_error` (502) / `engine_unavailable` (503)

Generation errors by endpoint

`missing_context_id` (400) / `context_not_found` (404)

`billing_unavailable` (503)

`upstream_unavailable` (502)

Handling Errors in Code