Documentation Index
Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
Use this file to discover all available pages before exploring further.
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 | 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.
}
