Error Catalog

All Lokutor API errors follow a single structured format:

{
  "code": "auth.invalid_key",
  "message": "The provided API key is invalid or has been revoked.",
  "detail": "Key sk_xxx...xxxx failed validation",
  "retryable": false
}

Field	Type	Description
`code`	`string`	Machine-readable identifier. Use this in switch statements.
`message`	`string`	Human-readable explanation suitable for UI display.
`detail`	`string`	Additional context (may contain request-specific data).
`retryable`	`boolean`	Whether the client should retry the request.

Authentication Errors

Errors that indicate the client cannot authenticate. Do not retry these without user intervention.

Code	HTTP Status	Meaning
`auth.missing_key`	`401`	No API key was provided. Pass it via `X-API-Key` header or `api_key` query parameter — see the note below on `Authorization: Bearer`.
`auth.invalid_key`	`401`	The API key is invalid, expired, or revoked.
`auth.rate_limited`	`429`	Too many requests from this IP or key, or too many sessions open at once (“Too many concurrent sessions”: 3 per account before the first top-up, 10 after, see Limits). Wait and retry with backoff, or close a session.
`auth.time_limited`	`429`	Demo time limit reached. Obtain a production API key.

Authorization: Bearer support varies by endpoint. /tts/synthesize, /stt/transcribe, and /denoise accept Authorization: Bearer, a raw Authorization header, X-API-Key, or ?api_key=. Every other authenticated endpoint (including the entire Call Center API) only accepts X-API-Key or ?api_key= — a Bearer token there is silently ignored and the request gets treated as unauthenticated. When in doubt, send X-API-Key; it works everywhere.

SDK handling:

client.onError = (error) => {
  if (error.code === 'auth.invalid_key') {
    showLoginModal();
  }
  if (error.code === 'auth.rate_limited') {
    showToast('Too many requests. Please wait.');
  }
};

Validation Errors

Errors that indicate the request was malformed. Fix the request payload and retry.

Code	HTTP Status	Meaning
`validation.invalid_voice`	`400`	The requested voice style does not exist.
`validation.invalid_language`	`400`	The requested language is not supported.
`validation.text_too_long`	`400`	Text exceeds the maximum length of 5000 characters.
`validation.speed_out_of_range`	`400`	Speed must be between 0.5 and 2.0.
`validation.steps_out_of_range`	`400`	Steps must be between 1 and 128.
`validation.invalid_request_format`	`400`	The request body could not be parsed.

TTS Errors

Errors during text-to-speech synthesis. Most are retryable.

Code	HTTP Status	Meaning	Retryable
`tts.synthesis_failed`	`503`	The TTS engine failed to generate audio.	Yes
`tts.voice_unavailable`	`503`	The requested voice style file is missing or corrupt.	Yes
`tts.model_not_found`	`503`	The model version is not loaded on this worker.	Yes
`tts.session_limit_reached`	`503`	The server is at capacity and cannot start another session right now. This limit is shared by all accounts; it is not your account’s own session limit, which answers `auth.rate_limited`.	Yes

STT Errors

Errors during speech-to-text transcription.

Code	HTTP Status	Meaning	Retryable
`stt.not_configured`	`503`	The STT engine is not enabled on this server.	No
`stt.stream_create_failed`	`503`	Failed to create an STT stream.	Yes
`stt.language_not_supported`	`503`	The requested language is not supported by the STT model.	No

Agent Errors

Errors during voice agent session management.

Code	HTTP Status	Meaning	Retryable
`agent.session_failed`	`503`	The orchestrator failed to create a session.	Yes
`agent.provider_error`	`503`	An upstream provider (LLM or TTS) returned an error.	Yes
`agent.not_found`	`404`	The `agent_id` does not exist or belongs to another account. A session may only use your own agents.	No

Billing Errors

Usage is paid from a prepaid balance (Pricing and billing). These errors mean the account cannot pay for what was asked; none of them goes away by retrying.

Code	HTTP Status	Meaning	Retryable
`billing.insufficient_balance`	`402`	The balance is below $0.25, the minimum to start a session or request (or, when buying a phone number, below its first month). The message states the balance. Top up in the dashboard (Billing), or turn on auto-recharge.	No
`billing.topup_required`	`402`	Calls your agent makes to phones (`/callcenter/dial`, bulk dial) and phone numbers need a first top-up: the welcome credit does not pay carriers.	No
`billing.account_disputed`	`402`	A payment on the account is disputed, and usage is paused until the dispute is resolved. Write to [email protected].	No
`billing.limit_reached`	`402`	Only for accounts still on a monthly plan while accounts move to the balance: the plan’s limit (agent minutes, TTS characters or STT minutes, depending on the endpoint) has been reached.	No

Where they arrive:

REST (/tts/synthesize, /stt/transcribe, /denoise): in the error format above.
Call Center API: as {"code": "billing.topup_required", "error": "…"}, with the same codes.
WebSocket (/ws/agent, /ws/tts, /ws/stt): the refusal comes before the connection opens. The handshake answers 402 with the message as plain text; a browser WebSocket only sees the connection fail (close code 1006), so check the balance when a connection fails at the handshake.

A call already in progress is not cut with an error when the balance runs out: the agent says goodbye and hangs up once the account is $2 below zero, and on the web the socket then closes with 1008 and the reason account balance exhausted. See When the balance runs out.

Internal Errors

Catch-all errors for unexpected server-side failures.

Code	HTTP Status	Meaning	Retryable
`internal.error`	`500`	An unexpected error occurred.	Yes
`internal.timeout`	`504`	The server timed out waiting for a downstream service.	Yes
`internal.cancelled`	`400`	The request was cancelled by the client or server.	No

Client-side (JavaScript SDK)

These are raised by @lokutor/sdk in the browser, not sent by the server.

Code	Meaning	Retryable
`audio.microphone_unavailable`	The microphone could not be started: permission refused (`detail` starts with `NotAllowedError`), no device (`NotFoundError`), or another capture failure. `connect()` rejects with it and the session is closed.	No

WebSocket Close Codes

When the connection closes, the WebSocket close code provides additional context:

Code	Name	Meaning	Retryable
`1000`	Normal	Clean closure by client or server, including a session nobody has spoken on for 5 minutes (reason `nobody has spoken for 5 minutes`).	No
`1001`	Going Away	Server is shutting down or client navigated away.	Yes
`1006`	Abnormal	Connection dropped unexpectedly (network issue, auth failure, CORS).	Yes
`1008`	Policy Violation	Rate limit or usage policy violated, or the account’s balance ran out during the session (reason `account balance exhausted`).	No
`1011`	Server Error	Internal server error caused the close.	Yes

Retry Strategy

Use this decision tree for every error:

import { isRetryable } from '@lokutor/sdk';

client.onError = (error) => {
  if (!isRetryable(error)) {
    // Fatal: show user, do not retry
    showErrorModal(error.message);
    return;
  }

  // Retryable: after a dropped connection the SDK reconnects up to 5 times
  // with exponential backoff (2s, 4s, 8s, 10s, 10s). A session the server
  // ended on purpose arrives as code 'session.ended' (not retryable).
  console.warn('Retryable error:', error.code, error.message);
};

Custom Retry Logic

If you are not using the SDK’s built-in reconnection:

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(attempt = 1) {
  try {
    await client.connect();
  } catch (error) {
    if (!isRetryable(error) || attempt > MAX_RETRIES) {
      throw error;
    }
    const delay = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), 10000);
    await sleep(delay + Math.random() * 1000); // jitter
    return connectWithRetry(attempt + 1);
  }
}

Get Started

SDK

API Reference

Resources

Authentication Errors

Validation Errors

TTS Errors

STT Errors

Agent Errors

Billing Errors

Internal Errors

Client-side (JavaScript SDK)

WebSocket Close Codes

Retry Strategy

Custom Retry Logic

​Authentication Errors

​Validation Errors

​TTS Errors

​STT Errors

​Agent Errors

​Billing Errors

​Internal Errors

​Client-side (JavaScript SDK)

​WebSocket Close Codes

​Retry Strategy

​Custom Retry Logic

​Related Pages

Authentication Errors

Validation Errors

TTS Errors

STT Errors

Agent Errors

Billing Errors

Internal Errors

Client-side (JavaScript SDK)

WebSocket Close Codes

Retry Strategy

Custom Retry Logic

Related Pages