Errors

Livqeno has five error vocabularies. They are separate on purpose: a chat failure, a media failure and a shader failure have almost nothing in common, and merging them would produce a list that describes none of them well.

Plus RTC error categories, which are a server-side classification of a failure that already happened — not a response code.

The HTTP error envelope

{
  "code": "RAVEN_ROOM_NOT_FOUND",
  "legacyCode": "NOT_FOUND",
  "message": "Room not found",
  "requestId": "req_9f2c41ab77e0c3d5b1a4e8f2",
  "path": "/v1/rooms/room_missing"
}

Some errors add fields — a 429 carries retryAfterSeconds. Ignore fields you do not recognise rather than treating them as an error.

HTTP error codes

Authentication and authorization

Not found

Most 404s here are environment mismatches: a development key cannot see a production room, and the room genuinely does not exist as far as that key is concerned.

Conflict

Request problems

MESSAGE_TOO_LARGE and ATTACHMENT_TOO_LARGE are separate because the two limits are configured independently — "make it smaller" is not actionable until you know which limit you crossed.

Infrastructure

Server-SDK-local codes

Raised by @ravenkash/server and raven-sdk before a request leaves the process, so they never appear in an HTTP body — but they share the namespace so one switch covers everything:

When a proxy returns an HTML error page instead of JSON, the SDK derives the code from the status — and derives it to the same name the API would have sent, so a 401 is RAVEN_AUTH_ERROR either way.

legacyCode and the migration

Before this namespace existed, code held bare values: NOT_FOUND, UNAUTHORIZED, VALIDATION_FAILED. Every error body now carries both.

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

legacyCode is lossy in one direction — several canonical codes map back to the same legacy value. That is the point: the new codes carry information the old ones did not. It is deprecated and will be removed.

RTC SDK errors

RTCError is the only error type @ravenkash/rtc throws or emits. Never a raw browser DOMException.

NOT_SUPPORTED and MEDIA_ERROR are deliberately distinct: one is a permanent fact about the device that a UI should act on, the other is a failure worth retrying.

import { isRTCError } from '@ravenkash/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

A classification applied server-side to a failure a client reported. You see these in the dashboard, in raven errors list, and on the observability API — never as a response code.

CONNECTION_FAILED is context-dependent, resolved in this order: a turn_unreachable hint → TURN_ERROR; a failed iceConnectionState → ICE_ERROR; signaling never reaching stable → SIGNALING_ERROR; otherwise SFU_ERROR.

Every classified error carries a likelyCause and suggestedAction, deliberately hedged ("likely a firewall/NAT restriction") rather than a claim of certainty a server cannot back up.

Chat errors

26 codes on the @ravenkash/chat side, 22 of which the gateway can put on an error frame. They map one-to-one onto SDK error classes so you can branch on the class rather than string-matching.

An unrecognised code from a newer server becomes a base RavenChatError with the code preserved, rather than an exception — an older client keeps working across a server upgrade.

Raw infrastructure failures never reach a client. A Postgres constraint violation or a Redis timeout is logged server-side and surfaces as INTERNAL_ERROR.

Chat WebSocket close codes

@ravenkash/chat treats 4401 and 4403 as terminal and reports failed rather than retrying forever.

Signaling errors

The RTC signaling WebSocket keeps its own vocabulary — it is a separately versioned wire protocol. You see these on an error frame, and the SDK maps most of them onto an RTCError.

Full frame contract in Signaling protocol.

Effects errors

Next steps

• Troubleshooting — symptoms rather than codes.
• Limits & quotas · Conventions