> ## 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.

# Error Codes

> Lookup table for KugelAudio TTS API error responses

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

```json theme={null}
{
  "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.                                  |

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

## 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.

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

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