Errors

Every error response includes ok: false and a machine-readable code.

Error envelope

{
  "ok": false,
  "code": "AUTH_REQUIRED",
  "detail": "Authentication required.",
  "error": "Authentication required."
}

Realtime WebSocket error frames

The realtime text-to-speech WebSocket reports errors as JSON error frames instead of HTTP responses. The frame carries the same machine-readable code values as the table below; the human-readable text is in message (the WebSocket counterpart of the HTTP envelope’s detail), and optional context is in meta:

{
  "type": "error",
  "code": "IDLE_TIMEOUT",
  "message": "Realtime TTS session timed out while idle."
}

The Status column shows each code’s default HTTP status; on the WebSocket the code arrives in an error frame, optionally followed by a close. Whether an error closes the session — and with which close code — is defined in the realtime guide.

Reference

Code	Status	Domain	Retry?	Default message
`BAD_REQUEST`	400	common	No	The request is invalid.
`AUTH_INVALID_SESSION`	401	auth	No	Invalid session.
`AUTH_REQUIRED`	401	auth	No	Authentication required.
`AUTH_SESSION_EXPIRED`	401	auth	No	Session expired.
`AUTH_USER_UNAVAILABLE`	401	auth	No	User not available.
`BILLING_INSUFFICIENT_CREDITS`	402	billing	No	Insufficient credits.
`AUTH_ADMIN_ACCESS_DENIED`	403	auth	No	Admin console access denied.
`AUTH_ADMIN_ROLE_REQUIRED`	403	auth	No	Admin role required.
`FORBIDDEN`	403	common	No	Forbidden.
`RESOURCE_NOT_FOUND`	404	common	No	Resource not found.
`IDLE_TIMEOUT`	408	realtime	Yes	Realtime session timed out while idle.
`SESSION_EXPIRED`	408	realtime	Yes	Realtime session reached its maximum duration.
`CONFLICT`	409	common	No	The request conflicts with current state.
`STUDIO_AUDIO_EXPORT_BLOCKED`	409	studio	No	Studio audio export is blocked by missing or stale clips.
`STUDIO_AUDIO_EXPORT_INCOMPATIBLE_AUDIO`	422	studio	No	Studio audio export requires compatible PCM WAV clip audio.
`STUDIO_AUDIO_EXPORT_NO_AUDIO`	422	studio	No	Studio audio export has no clip audio to export.
`STUDIO_AUDIO_EXPORT_UNSUPPORTED_SOURCE`	422	studio	No	Studio audio export requires supported clip audio sources.
`VALIDATION_ERROR`	422	common	No	Request validation failed.
`GENERATION_NOT_READY`	425	generation	Yes	Generation is not ready yet.
`GENERATION_CONCURRENCY_EXCEEDED`	429	generation	Yes	Your plan’s concurrent generation limit was reached. Please retry shortly.
`RATE_LIMITED`	429	common	Yes	Rate limit exceeded.
`INTERNAL_ERROR`	500	common	Yes	Internal server error.
`STUDIO_AUDIO_EXPORT_FAILED`	500	studio	Yes	Studio audio export failed.
`GENERATION_FAILED`	502	generation	Yes	Generation failed.
`GENERATION_INVALID_RESPONSE`	502	generation	Yes	Generation service returned an invalid response.
`UPSTREAM_ANALYTICS_ERROR`	502	upstream	Yes	Analytics service request failed.
`UPSTREAM_BILLING_ERROR`	502	upstream	Yes	Billing service request failed.
`UPSTREAM_GENERATION_ERROR`	502	upstream	Yes	Generation service request failed.
`UPSTREAM_GENERATION_SERVICE_ERROR`	502	upstream	No	Generation service request failed.
`VOICE_CLONE_FAILED`	502	voice	Yes	Voice clone failed.
`VOICE_DESIGN_FAILED`	502	voice	Yes	Voice design failed.
`AUTH_CONFIG_MISSING`	503	auth	No	Authentication is not configured correctly.
`DISPATCH_TIMEOUT`	503	generation	Yes	Generation dispatch timed out before execution. Please try again.
`GENERATION_CAPACITY_EXCEEDED`	503	generation	No	Generation capacity is currently exhausted. Please try again shortly.
`GENERATION_INTERRUPTED`	503	generation	Yes	Generation was interrupted by a service restart. Please try again.
`LLM_CONFIG_NOT_FOUND`	503	upstream	No	LLM feature is not configured.
`STUDIO_AUDIO_EXPORT_ASSET_READ_FAILED`	503	studio	Yes	Studio audio export could not read clip audio from storage.
`STUDIO_AUDIO_EXPORT_ASSET_WRITE_FAILED`	503	studio	Yes	Studio audio export could not write the result to storage.
`STUDIO_AUDIO_EXPORT_STORAGE_UNCONFIGURED`	503	studio	No	Studio audio export storage is not configured.
`UPSTREAM_ASSET_STORAGE_ERROR`	503	upstream	Yes	Audio asset storage failed.
`GENERATION_TIMEOUT`	504	generation	Yes	Generation timed out. Please try again.
`UPSTREAM_TIMEOUT`	504	upstream	Yes	Upstream request timed out.

Operational guidance

Authentication

Send API keys correctly and distinguish session-only account endpoints from API-key endpoints.

Rate limits

Retry concurrency, capacity, and timeout errors without overloading generation.

CLI troubleshooting

Map CLI exit codes to auth, quota, timeout, network, and dependency fixes.

Developer logs

Inspect failed requests, latency, request IDs, and generated cURL examples.

Get started

Concepts

Guides

Reference

Error envelope

Realtime WebSocket error frames

Reference

Operational guidance

Authentication

Rate limits

CLI troubleshooting

Developer logs

​Error envelope

​Realtime WebSocket error frames

​Reference

​Operational guidance

Authentication

Rate limits

CLI troubleshooting

Developer logs

Error envelope

Realtime WebSocket error frames

Reference

Operational guidance