Errors

This page lists every error code, what it means, and how to fix it. Come here when you have an error code in a log or on screen and need to know where it came from and what to change.

Errors happen at different steps of the flow — your backend minting a token, your user's app joining a call, a chat connection — and each step has its own list of codes. So the first question is: which step failed?

Which list is my error from?

Some names, like TOKEN_EXPIRED, appear in more than one list. Use the table above to know which one you're looking at.

Summary of the four lists:

There are also RTC error categories. These aren't response codes. They're labels Livqeno puts on failures after they happen, to help you debug.

What an HTTP error looks like

Any REST call can fail this way: from your backend with the API key, or from the dashboard and CLI. The body always has the same shape:

{
  "code": "RAVEN_ROOM_NOT_FOUND",
  "legacyCode": "NOT_FOUND",
  "message": "Room not found",
  "requestId": "req_d4a74eaeb970633fc42414a6",
  "path": "/v1/rooms/2f1b6c3e-8d4a-4b7e-9c21-5a0e7d3f9b10"
}

A validation error (RAVEN_VALIDATION_FAILED, 400) has two extra fields, statusCode and error. Its message can be a list, one entry per bad field:

{
  "message": ["environment must be one of the following values: DEVELOPMENT, STAGING, PRODUCTION"],
  "error": "Bad Request",
  "statusCode": 400,
  "code": "RAVEN_VALIDATION_FAILED",
  "legacyCode": "VALIDATION_FAILED",
  "requestId": "req_7f9f475ddcab0cb6f554f253",
  "path": "/v1/projects/…/api-keys"
}

So treat message as string | string[]. Ids in the URL are UUIDs. A badly formed id gets a 400, not a 404.

Some errors add more fields. For example, a 429 adds retryAfterSeconds. Ignore fields you don't know.

Catching errors on your backend

The server SDKs throw one error type, LivqenoError, with the same code and requestId as the HTTP body. A typical token endpoint on your backend (TypeScript):

import { isLivqenoError } from '@livqeno/server';
 
try {
  const grant = await livqeno.tokens.create({ room: roomId, identity: req.user.id });
  res.json(grant);
} catch (error) {
  if (isLivqenoError(error)) {
    // Log requestId so you can match this to Livqeno's records later.
    console.error(error.code, error.requestId);
    if (error.code === 'RAVEN_ROOM_NOT_FOUND') return res.status(404).end();
  }
  throw error;
}

HTTP error codes

These come back from the REST API. You'll mostly see them in your backend, when it creates rooms, tokens, or conversations with the API key. The dashboard and CLI show them too.

Login and access

Something is wrong with the credential itself: a bad API key, an expired token, or a dashboard sign-in that didn't finish.

Not found

The thing doesn't exist for this credential. It may exist in another project or environment.

Conflicts

The request is valid, but clashes with something that already exists. The most common one: two users join at once and both try to create the same room.

Bad requests

The request itself is wrong: a typo in a field name, a value out of range, or a body that's too big. Fix the request; retrying it unchanged won't help.

MESSAGE_TOO_LARGE and ATTACHMENT_TOO_LARGE are separate codes so you know which limit you hit.

RTC tokens

Usage limits

Your account has hit one of its free allowances or free-tier limits. You'll usually see these when your backend mints a token or creates a stream.

The last two are separate from USAGE_LIMIT_EXCEEDED so you can tell "wait" apart from "nothing left". A paid plan lifts all three.

Infrastructure

Something outside your request went wrong.

Errors from the server SDK itself

@livqeno/server and livqeno raise these before a request is sent, so they never appear in an HTTP response. They use the same RAVEN_* names, so one switch handles everything:

If a proxy returns an HTML error page instead of JSON, the SDK picks the code from the HTTP status. It uses the same code the API would have sent. For example, a 401 is always RAVEN_AUTH_ERROR.

legacyCode and old code

Before RAVEN_* codes existed, code held short values like NOT_FOUND, UNAUTHORIZED, and VALIDATION_FAILED. Every error now has both:

if (error.code === 'NOT_FOUND') { … }        // old — now error.legacyCode
if (error.code === 'RAVEN_ROOM_NOT_FOUND') { … }   // new

Several new codes map to the same old one, so the new codes tell you more. legacyCode is old and will be removed. Switch to code.

RTC SDK errors

These come from the RTC SDK in your user's browser or phone app: either thrown by join() and device calls like enableCamera(), or delivered to room.on('error'). @livqeno/rtc only ever throws or emits RTCError. Never a raw browser DOMException.

NOT_SUPPORTED means "never on this device". MEDIA_ERROR means "try again".

Handle them in your app code, and show the user something useful:

import { isRTCError } from '@livqeno/rtc';
 
room.on('error', (error) => {
  if (!isRTCError(error)) return;
  if (error.code === 'CAMERA_PERMISSION_DENIED') showPermissionHelp();
  if (error.code === 'NOT_SUPPORTED') hideFeature();
});

RTC error categories

You won't catch these in code. You'll see them when investigating a failed call afterwards. When a client reports a failure, Livqeno gives it a category to help you debug. You see these in the dashboard, in livqeno errors list, and in the observability API. They're never returned as a response code.

How CONNECTION_FAILED is categorized, checked in this order:

1. A turn_unreachable hint → TURN_ERROR
2. A failed iceConnectionState → ICE_ERROR
3. Signaling never became stable → SIGNALING_ERROR
4. Anything else → SFU_ERROR

Each categorized error has a likelyCause and a suggestedAction. They're worded as "likely", because the server can't be certain.

Chat errors

These come from chat: the chat SDK in your user's app, the chat WebSocket, or chat REST calls. @livqeno/chat has 26 codes. The server can send 22 of them in an error frame. Each code maps to one SDK error class, so you can check the class instead of comparing strings.

Chat WebSocket close codes

When the chat connection closes, the close code tells the app whether reconnecting makes sense. The SDK reads it for you; you only need this table if you're debugging or using the raw WebSocket.

@livqeno/chat stops on 4401 and 4403 and reports failed, instead of retrying forever.

Signaling errors

Signaling is the WebSocket an app opens to join a call; it's how the app and the media server agree how to connect. You'll only handle these codes directly if you speak the protocol yourself. With the SDK, you'll usually see them turned into an RTCError, or in logs.

The RTC signaling WebSocket has its own error codes, because it is a separately versioned protocol. You see them in an error frame. The SDK turns most of them into an RTCError.

The full message format is in Signaling protocol.

Close codes

These are the RTC signaling close codes (40xx). Don't confuse them with the chat close codes above (44xx).

When the server closes the signaling connection, it uses one of these codes. Where it applies, it sends an error frame first.

Next steps

• Troubleshooting: find a fix by symptom instead of code.
• Limits & quotas · Conventions