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.

On WebSockets the same object arrives inside an error frame: {"type": "error", "data": {"code", "message", "detail", "retryable"}}. On /ws/agent and /ws/stt, some runtime errors carry a plain string in data instead ({"type": "error", "data": "AI response service error."}); handle both. Two responses do not use this shape: the synthesis capacity 503 (below) and the Call Center API’s billing errors (below).

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 credential was provided. Send an API key or `wst_` ticket as `Authorization: Bearer <key>`, `X-API-Key: <key>`, or `?api_key=<key>`; every authenticated endpoint accepts all three.
`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.

SDK handling:

client.on('error', (error) => {
  if (error.code === 'auth.invalid_key') {
    showLoginModal();
  }
  if (error.code === 'auth.rate_limited') {
    showToast('Too many sessions open. Close one or wait.');
  }
});

You can also pass onError to the client’s constructor. It is a constructor option, not a property to assign later.

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`	The request is too big: more than 5,000 characters (on `POST /tts/synthesize`, counted across `text` and every segment), more than 200 segments, a `pause_ms` outside 0–10,000, or more than 60,000 ms of pauses in total. The `message` says which.
`validation.speed_out_of_range`	`400`	`speed` outside 0.5–2.0 on `/ws/tts`. (`POST /tts/synthesize` resets it to 1.0 instead.)
`validation.steps_out_of_range`	`400`	`steps` above 128 on `/ws/tts`. (`POST /tts/synthesize` treats anything above 8 as 8 instead.)
`validation.invalid_request_format`	`400`	The request could not be used: unparseable JSON, a missing required field (`text`, `voice`), a body over 1 MB, or audio that is not an accepted WAV format or is over 10 MB (`/stt/transcribe`, `/denoise`).

TTS Errors

Code	HTTP Status	Meaning	Retryable
`tts.synthesis_failed`	`503`	Synthesis failed on Lokutor’s side. On `/ws/tts` the error frame is followed by `EOS`, and the message is not billed.	Yes
`tts.session_limit_reached`	`503`	The server cannot start another voice-agent session right now. This limit is shared by all accounts; your account’s own session limit answers `auth.rate_limited`.	Yes

Synthesis at capacity

When every synthesis slot is busy, POST /tts/synthesize answers 503 with a Retry-After header (seconds) and a body that is not the error-catalog shape:

{
  "error": "synthesis capacity reached, retry shortly",
  "voice": "F1",
  "hint": "every stream slot on this worker is in use; the request was not malformed"
}

Wait Retry-After seconds and send the same request again.

Agent Errors

Code	HTTP Status	Meaning	Retryable
`agent.provider_error`	`503`	An upstream service failed: on `/denoise`, the denoiser is unavailable or failed; in agent sessions, the language model or synthesis.	Yes
`agent.not_found`	`404`	The `agent_id` does not exist or belongs to another account. A session may only use your own agents. Sent at the `/ws/agent` handshake.	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

Code	HTTP Status	Meaning	Retryable
`internal.error`	`500`	An unexpected error occurred.	Yes

Reserved codes

These codes are defined, and appear in the SDKs’ ErrorCode type, but the server does not send them today. Handle them generically (by retryable) if you match on codes exhaustively.

Code	HTTP Status	`retryable`
`tts.voice_unavailable`	`503`	`true`
`tts.model_not_found`	`503`	`true`
`stt.not_configured`	`503`	`true`
`stt.stream_create_failed`	`500`	`true`
`stt.language_not_supported`	`503`	`true`
`agent.session_failed`	`503`	`true`
`internal.timeout`	`504`	`true`
`internal.cancelled`	`400`	`false`

The JavaScript SDK’s TTSClient uses internal.timeout for its own client-side timeout (no audio within 30 s, or 15 s without a chunk); that one is never sent by the server.

Client-side codes (JavaScript SDK)

These are raised by @lokutor/sdk itself, 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
`session.ended`	The server closed the session on purpose (close code 1000, 1008 or 4xxx); `message` is the server’s reason. The SDK does not reconnect.	No
`ws.close`	The WebSocket failed or closed before the session was established.	Depends on the close code

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

Decide from retryable, and treat 402 (billing.*) as a prompt to top up rather than an error to retry. A complete recipe is in Error handling.

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

const client = new VoiceAgentClient({ auth: getTicket, agentId: 'your-agent-id' });

client.on('error', (error) => {
  if (error.code.startsWith('billing.')) {
    showTopUpPrompt(error.message);        // https://app.lokutor.com/billing
    return;
  }
  if (!isRetryable(error)) {
    showErrorModal(error.message);         // fix the request, the key or the agent
    return;
  }
  // Retryable. After a dropped connection the SDK reconnects by itself, up to 5 times
  // (2 s, 4 s, 8 s, 10 s, 10 s). A session the server ended on purpose arrives as
  // 'session.ended' and is not retried.
  console.warn('Transient error:', error.code, error.message);
});

Custom retry logic

If you connect yourself rather than relying on the SDK’s reconnection:

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

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function connectWithRetry(client: { connect(): Promise<unknown> }, maxRetries = 5) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await client.connect();
    } catch (error) {
      if (!isRetryable(error) || attempt >= maxRetries) throw error;
      const delay = Math.min(1000 * 2 ** attempt, 10000);
      await sleep(delay + Math.random() * 1000); // jitter
    }
  }
}

Get Started

SDK

API Reference

Resources

Authentication Errors

Validation Errors

TTS Errors

Synthesis at capacity

Agent Errors

Billing Errors

Internal Errors

Reserved codes

Client-side codes (JavaScript SDK)

WebSocket Close Codes

Retry Strategy

Custom retry logic

​Authentication Errors

​Validation Errors

​TTS Errors

​Synthesis at capacity

​Agent Errors

​Billing Errors

​Internal Errors

​Reserved codes

​Client-side codes (JavaScript SDK)

​WebSocket Close Codes

​Retry Strategy

​Custom retry logic

​Related Pages

Authentication Errors

Validation Errors

TTS Errors

Synthesis at capacity

Agent Errors

Billing Errors

Internal Errors

Reserved codes

Client-side codes (JavaScript SDK)

WebSocket Close Codes

Retry Strategy

Custom retry logic

Related Pages