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
}

HTTP and WebSocket payloads

Rows marked Retry-After also carry that response header on HTTP.

Refused WebSocket upgrades

/ws/tts, /ws/tts/stream, /ws/tts/multi and /v1/audio/enhance/stream authenticate before accepting the upgrade. A refused upgrade is an HTTP response, not a WebSocket close code: the client sees the HTTP status (for example 401 for a bad key, 429 when the organization's connection limit is reached, with Retry-After when known) and the JSON error envelope above as the body. Most WebSocket libraries expose this as a handshake or "invalid status" error.

WebSocket close codes

After the upgrade is accepted, errors arrive as JSON error frames. On the text-to-speech sockets most leave the socket open for the next turn. An error that closes the socket uses the close code for its error_code; the close code is separate from the JSON code.

Close codes 1012 and 1013 are not failures of your request. During a rolling deploy each replica finishes the turn it is generating, then closes idle sockets with 1012; a socket that was mid-turn receives its session_closed event first. Audio you already received is complete up to the last chunk. A handshake against a draining replica is accepted and immediately closed with 1013, so browser and server-side WebSocket clients receive the same portable restart signal. The SDK retry delay defaults to one second.

The Python and JavaScript SDKs absorb this for you. If no audio for the current turn has been delivered yet, they wait for the restart retry delay, reconnect to another replica, resend the turn (session config and open contexts included) and keep streaming, so a deploy is invisible to your users. Nothing is replayed once audio has started, because that would repeat what the listener already heard, and no turn is replayed twice. In those two cases the SDK raises the retryable ServerRestartingError and you decide what to resend. The JavaScript SDK also offers an onServerRestart callback for observing the silent replays; the Python SDK logs them at INFO on the kugelaudio.streaming logger. The Java SDK does not reconnect or replay: see Reconnecting after a server restart.

Request IDs

Every HTTP response carries an x-request-id header, on success and on error alike. WebSocket frames have no headers, so server-sent error frames carry the same value as a request_id field in the JSON body instead. The ID is minted when the connection opens and stays the same for every error frame on that connection.

A WebSocket connection that is refused before it opens, for example because the API key is invalid or a rate or connection limit was reached, gets an ordinary HTTP error response, and that response carries the x-request-id header too.

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

Quote this value in a support request: it is what lets us find the matching server-side logs for your exact call.

You can look the call up yourself too: paste the ID into the search on your project's Logs page in the dashboard. Every authenticated speech-generation request is logged, whether it succeeded, failed or was cancelled; a request refused for an invalid API key is not, because it cannot be tied to your organization. On a WebSocket every request sent over one connection shares the connection's ID, so the search returns all of them. The search needs at least 8 characters, so a shorter ID you send yourself cannot be looked up there.

If you already generate correlation IDs, send your own x-request-id request header and we echo it back. It must match [A-Za-z0-9_-] and be at most 64 characters; anything else is replaced with a generated ID rather than reflected.

All three SDKs surface the value on the typed error they raise, whichever of these three places it came from:

try:
    audio = client.generate(text="Hallo", voice_id=voice_id)
except KugelAudioError as exc:
    print(exc.request_id)

try {
  await client.generate({ text: 'Hallo', voiceId });
} catch (err) {
  console.log((err as KugelAudioError).requestId);
}

try {
    client.tts().generate(request);
} catch (KugelAudioException e) {
    System.out.println(e.getRequestId());
}

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

Find a request in your logs

The Logs page of your project in the dashboard lists the text-to-speech requests made in that project over up to the last 14 days. It covers the REST, WebSocket, ElevenLabs-compatible, Cognigy and Vapi endpoints. Each row shows:

• when the request finished
• whether it succeeded, failed or was cancelled, with the error_code for failures
• the endpoint, the model, the voice ID and the API key
• the audio duration, the character count and the cost
• a trace ID

To report a problem with a specific request, copy its trace ID and send it to support. With it we can find the exact request. A trace ID is 32 hexadecimal characters, for example:

4bf92f3577b34da6a3ce929d0e0e4736

You can also search the Logs page by trace ID. Requests rejected because the API key was missing or invalid do not appear, since they cannot be attributed to an organization.

Get an email when requests fail

Owners and admins turn on error alerts for a project with the Error alerts switch under Account settings → Email notifications, or with Alerts on the project's Logs page. Turned on, a project emails you when 5 or more requests fail within 5 minutes. Under Configure you can change:

• how many failed requests trigger an alert, and within which window (1, 5, 15 or 60 minutes)
• which errors count; by default every failure does
• which members of your organization get the email

The email names the number of failed requests, breaks them down by error code and endpoint, shows the trace ID of the latest failure and links to the failed requests on the Logs page. A project sends at most one alert email every 30 minutes, however long the errors go on. Error alerts cover text-to-speech requests and are off until you turn them on.