Errors

Every non-2xx response carries one fixed JSON shape, and every error.code is a stable machine-readable string you can branch on. This page is the canonical mapping of HTTP status to error.code, plus the two backpressure signals (429, 503) and the performance block that rides on success responses too.

The error envelope

Every non-2xx response — except in-stream SSE errors, which are delivered as an event: error frame — carries this exact shape:

{
  "error": {
    "code": "topic_not_found",
    "message": "topic \"orders\" does not exist",
    "detail": { "topic": "orders" }
  }
}

Success responses carry bare data — there is no {"status":"ok"} envelope. The presence of a top-level error key is the only success/failure discriminator.

Status codes

The complete status → error.code mapping. Clients branch on error.code, not the prose message.

A few codes are worth calling out:

• 401 vs 403 — 401 means no/invalid token; 403 means the token authenticates but lacks the required scope, or names a topic/router outside its prefix allowlist (enforced on the path and relevant request-body names). On watch: when the session was created with auth enabled it is bound to the creating key, so the SSE GET must present that same bearer (header or the dev-only ?token=) — a wrong key or no bearer at all is 401 (a leaked wid alone is not a credential). Only an unauthenticated (dev-mode) session opens on the wid alone.
• 409 not_a_queue — a queue endpoint (claim/ack/nack/extend/ work) was called on a plain "log" topic.
• 409 topic_exists_incompatible — a PUT tried to change a topic’s immutable type (log ↔ queue).
• 409 router_cycle — creating the router would introduce a directed cycle; error.detail.cycle lists the offending path, e.g. ["A","B","A"].

429 — throttle and resource caps

429 throttled is the single backpressure signal, raised in two situations. Both carry a Retry-After header; the error.detail distinguishes them so a client can react correctly.

CPU-pressure throttle — the elastic scheduler is shedding load. The detail carries a suggested wait:

{ "error": {
    "code": "throttled",
    "message": "throttled under CPU pressure",
    "detail": { "retry_after_ms": 1500 } } }

Resource cap reached — a configurable resource limit (max topics, routers, watch sessions, SSE connections, in-flight requests per key, or total retained bytes) would be exceeded. The detail names the cap:

{ "error": {
    "code": "throttled",
    "message": "max topics reached",
    "detail": { "limit": "max_topics", "max": 100000 } } }

503 — not ready / shutting down

503 is the lifecycle backpressure signal, raised by the readiness gate and by ordinary endpoints during boot or drain. It always carries a Retry-After header.

• not_ready — boot-time WAL replay is in progress. The detail carries replay_progress (0.0–1.0):

  { "error": {
      "code": "not_ready",
      "message": "WAL replay in progress",
      "detail": { "replay_progress": 0.62 } } }

• shutting_down — the server received SIGINT/SIGTERM and is draining in-flight work before writing a final snapshot and exiting.

Route traffic on /v0/ready so a 503-during-replay node is taken out of rotation until it flips to 200. See Health & Metrics and Recovery.

The performance block

Every JSON response — and most errors — includes a performance object, so per-request observability lives in the response rather than a side channel:

"performance": {
  "server_total_ms": 0.41,
  "wal_append_ms": 0.12,
  "fsync_ms": 0.0,
  "records_scanned": 128,
  "throttle_wait_ms": 0.0
}

Fields are best-effort and additive — clients must tolerate any subset, and each field is omitted when it does not apply.

See also

• API Conventions — auth, content types, the $-metadata convention, idempotency.
• Health & Metrics — the 503 readiness gate in detail.
• Tombstones — why involuntary loss is a 200 signal, not an error.
• Security — scopes and prefix allowlist behind 401/403.