Error codes

Every Sirannon error extends SirannonError and includes a machine-readable code. Match on the code. The message explains what happened to a human reading a log and changes between releases, so treat it as prose. catch-errors.ts inserts an order with no total, which the column's NOT NULL constraint refuses.

mkdir -p data

import { QueryError, Sirannon } from '@delali/sirannon-db'
import { betterSqlite3 } from '@delali/sirannon-db/driver/better-sqlite3'
 
const driver = betterSqlite3()
const sirannon = new Sirannon({ driver })
 
const db = await sirannon.open('shop', './data/shop.db')
 
await db.execute('CREATE TABLE IF NOT EXISTS orders (id INTEGER PRIMARY KEY, total REAL NOT NULL)')
 
try {
  await db.execute('INSERT INTO orders (id) VALUES (?)', [1])
} catch (err) {
  if (err instanceof QueryError) {
    console.error(`SQL failed [${err.code}]: ${err.message}`, err.sql)
  }
}
 
await sirannon.close('shop')

SQL failed [QUERY_ERROR]: NOT NULL constraint failed: orders.total INSERT INTO orders (id) VALUES (?)

Some errors add context alongside the code: sql on QUERY_ERROR, table, rowId, and cause on CONFLICT_ERROR, version on a migration error, limit and retryAfterMs on WRITE_OVERLOADED, requestId on SYNC_ERROR, and serverVersion on MIGRATION_REQUIRED and SCHEMA_AHEAD.

Over the network, an HTTP response and a WebSocket error message use the same shape:

{ "error": { "code": "ERROR_CODE", "message": "Human-readable description", "details": {} } }

A dash in a class column below means Sirannon raises the base SirannonError with that code, so match on err.code for those.

Core engine

Writer worker

The writer worker separates a rejected write from one whose outcome is unknown, which is the difference between retrying safely and reconciling first.

Backups

A backup writes to storage you own, so whether a failure is worth retrying depends on what that failure left behind. Sirannon removes a partial local file itself, and a destination that follows the contract lets a later run replace any piece an earlier one stored.

Migrations

Server and requests

Registered operations

Every code here comes from registered operations, and each one names a specific mistake in the request.

Replication

Every class here is exported from @delali/sirannon-db/replication, and FailoverError is the shared base of NoSafePrimaryError and UnsafeRecoveryRequiredError.

Device sync

Optional packages

Sirannon raises these codes in your own process when it starts a server, a replication transport, or a coordinator whose package it cannot load. The message names the missing package and the command that installs it.

Client

Deciding whether to retry

Three groups behave differently, and treating them alike is how a retry loop corrupts data.

• Definite rejections are safe to send again. WRITE_OVERLOADED reports load shedding, because the write never ran, the response includes Retry-After, and the same request is safe to repeat. WRITER_WORKER_UNAVAILABLE and WRITER_WORKER_POST_FAILED report the same about a write that never reached the writer.
• Indeterminate outcomes need reconciling first. WRITER_WORKER_TIMEOUT and WRITER_WORKER_EXIT leave the outcome unknown, so read the state back before resending anything that is not idempotent.
• Stale routing needs a refresh, not a retry. STALE_PRIMARY, AUTHORITY_LOST, COORDINATOR_UNAVAILABLE, NO_SAFE_PRIMARY, and CONNECTION_ERROR mean the client's view of the cluster is out of date. The topology client refreshes its routing metadata on all five in coordinator mode and runs a failed read once more, while it raises a failed write for you to reconcile.

A validation code such as INVALID_WRITER_WORKER, INVALID_MAX_BODY_BYTES, INVALID_DRIVER, or INVALID_ARGUMENT reports a configuration or call-site mistake. Fix the configuration; retrying reproduces it.

UNAUTHORIZED and FORBIDDEN report a refused WebSocket upgrade, and the server refuses that credential every time. The client leaves the connection closed, so issue a fresh credential and build a new client.

HTTP status codes

A code outside the table maps to 500, and a RequestDeniedError uses the status you gave it. WRITER_WORKER_TIMEOUT maps to 500, and not to 503, precisely because its outcome is indeterminate, so no proxy in front of the server treats it as a routine retry.

WebSocket close codes

A status code reaches an HTTP caller, and a close code reaches a socket. No WebSocket client can read the status of a refused handshake, so the server reports those refusals in the close code.

The client reconnects after 4290 and resumes each subscription from its cursor. It reads any code from 4000 to 4099 as a refusal and leaves that connection closed, because the server refuses that credential every time.