Errors

The API returns errors as JSON with an error code and a human-readable message.

Error Format

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

Field	Type	Description
`error`	string	Machine-readable error code
`message`	string	Human-readable description

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

`invalid_json` / `missing_transcript` (400)

The request body is malformed or missing required fields. Common causes:

Invalid JSON body
Missing transcript, voice, model_id, or output_format

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

Errors

`unauthorized` (401)

`invalid_json` / `missing_transcript` (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

​Errors

​unauthorized (401)

​invalid_json / missing_transcript (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

Errors

`unauthorized` (401)

`invalid_json` / `missing_transcript` (400)

Invalid `output_format` (400)

`payment_required` (402)

`rate_limited` / `concurrent_limit` (429)

`billing_unavailable` (503)

`upstream_unavailable` (502)

Handling Errors in Code