Error Codes

Raven has three error vocabularies, and they are separate on purpose:

A chat failure and a media failure have almost nothing in common, and merging them would produce a list that describes neither well.

The HTTP error envelope

Every error the REST API returns has the same shape:

{
  "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, for example. Unknown fields should be ignored rather than treated as an error.

Request IDs

Every response carries x-request-id. Error bodies repeat it as requestId so a developer copying a JSON blob into an issue does not lose it.

Send your own and Raven will adopt it, letting one call be traced across your logs and ours:

x-request-id: 7c1f9e2a-your-own-correlation-id

An inbound value is accepted only when it is 1–64 characters of A-Za-z0-9_-. Anything else — a newline, a control character, a megabyte of text — is discarded and a fresh ID generated. That value ends up in log lines and error bodies, so a half-sanitised identifier is worth less than an honest new one. Generated IDs look like req_ followed by 24 hex characters.

Canonical codes

Codes are grouped so that anything a caller would handle the same way shares one code, and anything needing a different fix gets its own. RAVEN_MESSAGE_TOO_LARGE and RAVEN_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.

SDK-side codes

The server SDKs use the same namespace for failures that never reach the API, so one switch covers everything:

RAVEN_TIMEOUT, RAVEN_NETWORK_ERROR, RAVEN_INVALID_CONFIG, RAVEN_UNKNOWN_ERROR.

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, and the chat codes such as INVALID_CURSOR. Anything switching on those keeps working: every error body now carries both, with legacyCode holding exactly what that error used to emit.

// Old — still works, for now
if (error.code === 'NOT_FOUND') { ... }        // now error.legacyCode
 
// New
if (error.code === 'RAVEN_ROOM_NOT_FOUND') { ... }

legacyCode is deprecated and will be removed. Nothing in this repository reads it; it exists purely for callers we cannot see. Migrate by switching on code and deleting any reference to legacyCode.

Note that legacyCode is lossy in one direction: several canonical codes map back to the same legacy value (RAVEN_ROOM_NOT_FOUND and RAVEN_MESSAGE_NOT_FOUND were both NOT_FOUND). That is the point — the new codes carry information the old ones did not.

RTC errors

Every RTC error a developer sees — in the dashboard, in raven errors, or in an @corvidhq/rtc error event — is a Raven concept, never a raw SFU or TURN error code. One place server-side maps the underlying error into this taxonomy.

Categories

SDK error code → category mapping

CONNECTION_FAILED is context-dependent, checked in this order:

1. A hint: 'turn_unreachable' in the reported data → TURN_ERROR.
2. iceConnectionState of failed/disconnected → ICE_ERROR.
3. signalingState never reached stable/connected → SIGNALING_ERROR.
4. Otherwise → SFU_ERROR (no more specific signal available).

Smart explanations — hedged, never certain

Every classified error carries a likelyCause and suggestedAction — deliberately hedged language ("likely a firewall/NAT restriction"), never a claim of certainty a Raven server can't actually back up. Examples:

• TOKEN_ERROR: "The RTC token had already expired before (or during) the connection attempt." → "Mint a fresh RTC token — tokens are always short-lived by design."
• ICE_ERROR: "ICE connectivity checks failed between the client and the media server — likely a firewall/NAT restriction." → "Ensure TURN is reachable from this network; corporate proxies/firewalls are the most common cause."
• TURN_ERROR: "Unable to establish a TURN relay connection — possibly a restrictive firewall/NAT blocking UDP." → "Check whether UDP traffic is blocked; try a TCP/TLS TURN transport instead."

Where to see this

• raven errors list / raven errors inspect <errorId> — see CLI
• Dashboard → a project's Errors tab and error detail page
• GET /v1/projects/:projectId/errors / /errors/:errorId (JWT-guarded)

Chat frame codes

These are the codes on the WebSocket error frame. Over HTTP the same failures arrive as RAVEN_* codes (with the chat code preserved in legacyCode) — see the envelope section above. The frame keeps its own vocabulary because it is a separately versioned wire protocol that @corvidhq/chat already maps.

Every failure from the chat API or @corvidhq/chat carries one of these codes. They are stable, and they map one-to-one onto SDK error classes so a caller can branch on the class rather than string-matching a message.

Raw infrastructure errors never reach a client: a Postgres constraint violation, a Redis timeout, or an unhandled exception is logged server-side in full and surfaces as INTERNAL_ERROR.

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

WebSocket close codes

Where to see this

• Dashboard → a project's Chat section
• @corvidhq/chat's error event and rejected promises
• WebSocket Protocol for the frame-level contract