Error codes

Every Sirannon error extends SirannonError and carries 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 rather than an identifier. 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 carry extra context alongside the code: sql on QUERY_ERROR, table and rowId 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 carry 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.

Migrations

Server and requests

Registered operations

Every code here comes from registered operations, and each names a specific mistake in the request rather than a general failure.

Replication

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

Device sync

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 is load shedding: the write never ran, the response carries Retry-After, and the same request is safe to repeat. WRITER_WORKER_UNAVAILABLE and WRITER_WORKER_POST_FAILED say the same thing 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, and raises a failed write rather than resending it.

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 rather than 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.