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

`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 project's per-minute request rate or concurrency cap. See Rate Limits.

Fix: Honor the Retry-After header and retry.

`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

Node.js

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

Errors

On this page