Error Codes

VoiceMaker returns standard HTTP status codes along with a consistent JSON error body. Every error carries a stable, machine-readable errorCode — branch on it rather than on the error/detail text, which may be reworded — and a requestId you can quote when contacting support.

Error response format

{
  "error": "Invalid request",
  "detail": "Request body did not match the expected schema.",
  "errorCode": "invalid_payload",
  "requestId": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "issues": [
    { "field": "voice_id", "code": "too_small", "message": "Required" }
  ]
}

Rate-limit responses (429) and cold-start responses (503) also send a Retry-After header with the number of seconds to wait.

HTTP status codes

Error-code catalog

The SDK exception column is the class the official SDKs raise for the code (same names in JavaScript and Python; every SDK error also exposes the code as err.code / e.code). Subclasses are listed where they exist — for example UnknownVoiceError is also a ValidationError, and ServiceWarmingError is also a ServiceUnavailableError.

Authentication & authorisation

Request validation

Transcription input

Voices

Credits & limits

Availability

Processing

Any code this page does not list yet is still delivered in the same body shape; the SDKs map it by HTTP status and keep the raw code on err.code.

Streaming errors

The WebSocket endpoints (/transcribe/stream, /tts/stream) answer a refused connection with a plain HTTP error from the catalog above before the upgrade — 401, 402 (insufficient_credits for the reserve block), 403, 400/422 (voice_id_required, unknown_voice_id, voice_not_ready, unsupported_language, streaming_unsupported_language), 429 (stream_concurrency_limit), or 503 (tts_warming, stream_capacity, streaming_unavailable). Browsers hide that status from JavaScript, so the JavaScript SDK emits an error event with code upgrade_rejected and the likely causes; the Python SDK reads the body from the rejected handshake and raises the same typed exception a REST call would.

Once a session is open, errors arrive as { "type": "error", "code", "message" } frames. The session may continue afterwards or be closing, as noted:

Close codes

SDK-side errors

The SDKs also raise errors of their own before or instead of a request. They share the code field with API errors:

Common error scenarios

Voice required (400)

Every text-to-speech request needs a voice_id (batch POST /dev/v1/tts/generate and the /dev/v1/tts/stream WebSocket alike). A missing or blank voice_id is refused before anything else is validated:

{
  "error": "Voice required",
  "detail": "Specify a voice_id.",
  "errorCode": "voice_id_required",
  "requestId": "..."
}

Pick an ID from GET /dev/v1/tts/voices.

Unknown voice (422)

{
  "error": "Unknown voice",
  "detail": "voice_id 'foo' does not match an enabled voice preset or one of your custom voices. Use GET /dev/v1/tts/voices for the list of available voices.",
  "errorCode": "unknown_voice_id",
  "requestId": "..."
}

Voice not ready (422)

The voice_id matched one of your custom cloned voices, but the voice cannot synthesize yet (still processing, failed, or missing its reference assets).

{
  "error": "Voice not ready",
  "detail": "Custom voice 'My Studio Clone' is not ready for synthesis (status: PROCESSING)",
  "errorCode": "voice_not_ready",
  "requestId": "..."
}

Insufficient credits (402)

{
  "error": "Insufficient credits",
  "detail": "Not enough purchased credits. Required: 1,500 credits.",
  "errorCode": "insufficient_credits",
  "requestId": "..."
}

File too large (413)

{
  "error": "File too large",
  "detail": "Audio file exceeds the 25MB limit for your current plan.",
  "errorCode": "file_size_limit_exceeded",
  "requestId": "..."
}

Engine warming up (503)

Synchronous TTS on a cold engine answers 503 with Retry-After: 60. Retry after that, or submit with mode: "async" and poll GET /dev/v1/tts/{id}.

{
  "error": "TTS engine warming up",
  "detail": "The TTS engine is starting up (cold start). Retry in ~1 minute, or submit with mode:\"async\" to queue the job and poll GET /dev/v1/tts/:id.",
  "errorCode": "tts_warming",
  "requestId": "..."
}

Rate limited (429)

{
  "error": "Rate limit exceeded",
  "detail": "This developer API key has exceeded its current rate limit",
  "errorCode": "rate_limited",
  "requestId": "..."
}

Inspect the Retry-After header to learn how long to wait before retrying.

Handling errors in the SDKs

Both SDKs raise typed exceptions whose message names the SDK method that failed, rewrites endpoint references into SDK calls, and ends with the code and request id:

tts.generate(): Unknown voice — voice_id 'foo' does not match an enabled voice
preset or one of your custom voices. Use tts.listVoices() for the list of
available voices. [unknown_voice_id · request 8f1c2d3e]

import { UnknownVoiceError, ServiceWarmingError, VoiceMakerAPIError } from "myvoicemaker";

try {
  await client.tts.generate({ text, voice_id });
} catch (err) {
  if (err instanceof UnknownVoiceError) { /* pick from client.tts.listVoices() */ }
  else if (err instanceof ServiceWarmingError) { /* retry in err.retryAfter s, or mode: "async" */ }
  else if (err instanceof VoiceMakerAPIError) { console.error(err.code, err.requestId, err.hint); }
}

from myvoicemaker import UnknownVoiceError, ServiceWarmingError, VoiceMakerAPIError

try:
    client.tts.generate(text, voice_id=voice_id)
except UnknownVoiceError:
    ...  # pick from client.tts.list_voices()
except ServiceWarmingError as e:
    ...  # retry in e.retry_after s, or mode="async"
except VoiceMakerAPIError as e:
    print(e.code, e.request_id, e.hint)

Every SDK error exposes code, method, hint, description, retryable, retryAfter/retry_after, requestId/request_id and issues; the full class trees are in each SDK's README.