Error Codes

KugelAudio TTS endpoints return the same error shape for HTTP responses and WebSocket error frames.

{
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "code": 429
}

Field	Type	Description
`error`	string	Safe client-facing message. Do not parse this field for program logic.
`error_code`	string	Stable machine-readable error category.
`code`	integer	HTTP-style status code for the error.

retry_after is not included in the JSON body. When retry timing is available for an HTTP response, use the Retry-After response header.

HTTP and WebSocket payloads

Status / payload `code`	`error_code`	Message	Meaning
`400`	`VALIDATION_ERROR`	`Invalid request`	The request payload or WebSocket message is malformed or invalid.
`400`	`VALIDATION_ERROR`	`Invalid JSON body`	The HTTP request body is not valid JSON.
`400`	`VALIDATION_ERROR`	`text required`	The request is missing text to synthesize.
`400`	`MISSING_VOICE_ID`	`voice_id is required`	No `voice_id` was supplied for synthesis. There is no default voice — set a `voice_id`. Distinct from the `404` “voice doesn’t exist” case below.
`400`	`VALIDATION_ERROR`	`Unsupported audio format`	Uploaded reference audio uses an unsupported file format.
`400`	`VALIDATION_ERROR`	`Invalid voice metadata`	Voice creation metadata could not be parsed or validated.
`401`	`UNAUTHORIZED`	`Unauthorized`	The API key is missing, invalid, or not accepted for this request.
`402`	`INSUFFICIENT_CREDITS`	`Insufficient credits`	The organization does not have enough credits for the request.
`403`	`UNAUTHORIZED`	`Forbidden`	The API key is valid, but it cannot access the requested resource.
`404`	`NOT_FOUND`	`Voice not found`	The requested voice does not exist or is not visible to the caller.
`404`	`NOT_FOUND`	`Dictionary not found`	The requested dictionary does not exist or is not visible to the caller.
`404`	`NOT_FOUND`	`Entry not found`	The requested dictionary entry does not exist or is not visible to the caller.
`404`	`NOT_FOUND`	`Project not found`	The requested project does not exist or is not visible to the caller.
`404`	`NOT_FOUND`	`Reference not found`	The requested voice reference does not exist or is not visible to the caller.
`429`	`RATE_LIMITED`	`Rate limit exceeded`	The organization exceeded its rate limit.
`429`	`RATE_LIMITED`	`Request exceeds the maximum character limit`	The text is longer than the organization tier allows for one request.
`500`	`INTERNAL_ERROR`	`Audio generation failed`	The generation request failed before usable audio could be returned.
`500`	`INTERNAL_ERROR`	`Sample generation failed`	Voice sample generation failed.
`500`	`INTERNAL_ERROR`	`Failed to fetch voice`	Voice metadata could not be loaded.
`503`	`MODEL_UNAVAILABLE`	`Model overloaded, please try again later.`	Cluster capacity is temporarily full. Retry later.
`503`	`MODEL_UNAVAILABLE`	`The requested model is temporarily unavailable. Please try again shortly.`	The selected model is temporarily unavailable.

WebSocket close codes

WebSocket error frames use the same JSON payload shape as HTTP errors. If the server closes the socket after sending an error, the WebSocket close code is separate from the JSON code.

WebSocket close code	Related `error_code`	Meaning
`4001`	`UNAUTHORIZED`	Authentication failed.
`4003`	`INSUFFICIENT_CREDITS`	The organization does not have enough credits.
`4029`	`RATE_LIMITED`	The organization exceeded its rate limit.
`4500`	`MODEL_UNAVAILABLE`	The selected model is temporarily unavailable or overloaded.
`4000`	`INTERNAL_ERROR`	The connection closed because of a generic generation failure.

Handling errors

Use error_code and code for application logic. Treat error as display text only.

if (message.error_code === "RATE_LIMITED") {
  // Back off and retry later.
}

if (message.error_code === "MODEL_UNAVAILABLE") {
  // The model or cluster is temporarily overloaded.
}

Get started

Build a voice agent

Generate audio

Voices

Deploy

SDK Reference

API Reference

HTTP and WebSocket payloads

WebSocket close codes

Handling errors

​HTTP and WebSocket payloads

​WebSocket close codes

​Handling errors

HTTP and WebSocket payloads

WebSocket close codes

Handling errors