Errors

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

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 uses the shorter { "error": "...", "message": "..." } shape (no error_code/detail). 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 predicts more than ~46.5s of audio
`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
`invalid_language`	400	voices/clone	`language` is not a well-formed BCP-47 tag

`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 instead of a silent done — 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.

`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)

A single request can synthesize at most ~46.5 seconds of audio — the generator’s hard ceiling. The limit is on predicted spoken duration, not character count: the estimate is digit-aware and per-language, and a digit is spoken as a whole word (4 → “four”), so number-heavy text hits the limit with far less text. As a rough en-US guide, that’s ~900 characters of normal prose but only ~130 digits (phone numbers, amounts, codes, dates). The exact threshold shifts slightly by voice language. The check runs before synthesis, so nothing is billed on a rejection. On /tts/bytes and /tts/sse this is an HTTP 400 (on SSE it’s returned before the event stream opens, as a normal HTTP body — not an in-stream event):

{ "error": "input_too_long", "error_code": "input_too_long", "message": "transcript predicts ~54.1s of audio, over the 46.5s limit; send shorter text", "detail": "transcript predicts ~54.1s of audio, over the 46.5s limit; send shorter text" }

On the WebSocket it’s a per-context error frame; the socket stays open and other contexts/turns are unaffected:

{ "type": "error", "context_id": "c2", "done": true, "error_code": "input_too_long", "status_code": 400, "title": "Input Too Long", "message": "transcript predicts ~54.1s of audio, over the 46.5s limit; send shorter text", "doc_url": "", "request_id": "9f2c1a7b8e4d4f0a" }

Fix: Keep each request under ~46.5s of speech (~900 characters of prose, fewer for number-heavy text) and split longer content into multiple requests. Over WebSocket, stream it across turns with continue: true, keeping each turn under the limit.

`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). This endpoint uses the shorter { error, message } shape.

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

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 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 credit balance can’t cover the request.

{ "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.

`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. Any pre-charge is refunded automatically. 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 — retry later");
    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)

Invalid or malformed body (400)

Invalid `output_format` (400)

`payment_required` (402)

`rate_limited` / `concurrent_limit` (429)

`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)

​Invalid or malformed body (400)

​Invalid output_format (400)

​payment_required (402)

​rate_limited / concurrent_limit (429)

​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)

Invalid or malformed body (400)

Invalid `output_format` (400)

`payment_required` (402)

`rate_limited` / `concurrent_limit` (429)

`billing_unavailable` (503)

`upstream_unavailable` (502)

Handling Errors in Code