Errors and limits

Error format#

Every non-2xx response carries an ApiError body:

{
  "code": "ERROR_CODE_FORBIDDEN",
  "message": "not available for bots",
  "field": "",
  "reason": "BOT_NOT_ALLOWED"
}

The full code list is in Error codes.

Common bot errors#

Limits#

Requests per second and messages per minute are plenty for integrations but not for mass mailing. On a self-hosted server the operator can change the bot limits with BOT_RATE_PER_SEC and BOT_MESSAGES_PER_MIN. All limits: Limits.

Retries and idempotency#

• 429 — wait Retry-After seconds and retry. The SDK does this itself up to maxRetries times.
• 5xx and network drops — retry with exponential backoff.
• Messages — send them with a nonce: a retry with the same nonce returns the message already created (200) instead of a duplicate.
• Forms — submit with a stable UUID nonce: identical submissions create one task.
• Events (gateway, webhook) may arrive twice — dedupe by delivery id, seq or press id.
• 4xx other than 429 — don't retry without changing the request.

async function call(url, init, tries = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429 && res.status < 500) return res;
    if (i === tries - 1) return res;
    const wait = Number(res.headers.get('Retry-After')) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

import time, requests

def call(method, url, tries=5, **kw):
    for i in range(tries):
        r = requests.request(method, url, **kw)
        if r.status_code != 429 and r.status_code < 500 or i == tries - 1:
            return r
        time.sleep(float(r.headers.get("Retry-After", 2 ** i)))

FAQ#

The bot doesn't see a room or messages. It lacks VIEW_ROOM: the room is private, restricted (only through an override on it), or the bot's role grants no access. Check the roles and the room's overrides.

The bot doesn't answer /cmd. Nobody registered the command, or several bots in the room did — write /cmd@username. Messages written by bots are never commands.

Do I need the gateway if I have a webhook? No. A webhook bot works through REST and the webhook and counts as online while it makes requests. Voice events, though, arrive only over the gateway.

Two processes with one token? No — the second pushes the first out. To scale, use a webhook with processing by id, or several bots.

Does the bot hear itself in a call? No: LiveKit never sends a participant its own tracks. The SDK skips the bot's own messages and reactions by default (receiveOwn: true turns them on).