Error handling — classify, contain, surface

You are designing what happens whenever anything in a class breaks, not chasing one crash (that is debug). Every failure gets classified, contained, and surfaced — never swallowed. The deliverable, in that order: a typed error taxonomy, a retry policy with caps and jitter, boundary placement, and a two-audience message contract — never a pile of try { … } catch {}.

Step 1 — Model failure as a taxonomy

Bucket every failure into one of three kinds. The bucket dictates the reaction; get the bucket wrong and every downstream decision is wrong too.

Bucket	Examples	Retry?	Tell the user	Tell the operator
Domain / expected	insufficient funds, slot taken, validation failed	No	Yes, actionable	info — it is normal
Infrastructure / transient	timeout, 503, connection reset, 429	Yes (capped)	"temporary, retrying"	warn — watch the rate
Programmer error / bug	null deref, bad assertion, type error	No	generic "something broke" + id	error — page if frequent

Result vs throw

Decide per call site, not per codebase:

• Result<T, E> for expected domain failures the caller must handle. The type checker forces a branch — the failure cannot be ignored by accident.
• throw for exceptional / programmer errors. These should crash up to the nearest boundary, not be threaded through every signature.

In TypeScript, neverthrow (current) is the instrument for the Result path:

import { ok, err, Result } from "neverthrow";

type ChargeError = "insufficient_funds" | "card_declined";

// Expected domain failure → Result. The caller MUST handle both arms.
function charge(cents: number, balance: number): Result<number, ChargeError> {
  if (cents > balance) return err("insufficient_funds");
  return ok(balance - cents);
}

const r = charge(500, 200);
if (r.isErr()) {
  // r.error is the typed union — exhaustive, no `any`.
}

Stable codes and cause chaining

Every error carries a stable code (a string the UI and logs key off, never the human message) and never drops the original cause.

// BAD — string error, loses the original, nothing to branch on.
throw new Error("payment failed");

// GOOD — typed class, stable code, cause preserved.
class PaymentError extends Error {
  constructor(public code: "provider_down" | "declined", cause?: unknown) {
    super(code);
    this.name = "PaymentError";
    this.cause = cause; // the original error/stack survives for the log
  }
}
try {
  await provider.charge();
} catch (e) {
  throw new PaymentError("provider_down", e); // wrap, do not erase
}

Cross-language error-class skeletons (Python, Java, Go, .NET) live in references/retry-and-resilience.md.

Step 2 — Decide retryability

Retry only transient failures, and only on idempotent operations. Retrying the wrong thing turns one slow dependency into a self-inflicted outage.

Retry these (transient)	Never retry these (permanent)
Network error, connection reset	400 bad request, 422 unprocessable
Timeout	401 / 403 (auth/permission)
429 too many requests (honor Retry-After)	404 not found
503 / 502 / 504	Any business-rule rejection (insufficient funds)
500 on a GET (idempotent)	500 on a non-idempotent POST without a key

Idempotency is a precondition, not a nicety. A retried POST that creates a charge can double-charge. Retry only operations that are idempotent by nature (GET, PUT, DELETE) or that carry an idempotency key so the server dedupes. Key design itself belongs to ../api-design/SKILL.md; here you just require one before you retry a mutation.

Caps (industry-converged — AWS Builders' Library, REL05-BP03):

• Max 3–5 total attempts.
• Base delay 100–200ms, doubling per attempt.
• Per-delay cap 10–30s; total retry budget 10–60s then give up.
• Full jitter to spread load — beats fixed and equal jitter:

delay = random_between(0, min(cap, base * 2 ** attempt))

Set a per-attempt timeout first, then retry — a retry on a call that never times out just stacks hung requests.

// GOOD — classify before retrying; cap; full jitter; per-attempt timeout.
async function withRetry<T>(fn: () => Promise<T>, max = 4): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn(); // fn must enforce its own per-attempt timeout
    } catch (e) {
      if (!isTransient(e) || attempt >= max - 1) throw e; // permanent or budget spent
      const cap = 10_000, base = 150;
      const delay = Math.random() * Math.min(cap, base * 2 ** attempt); // full jitter
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Per-language withRetry (Python tenacity, Java Resilience4j, .NET Polly) is in references/retry-and-resilience.md.

Step 3 — Contain blast radius

Retries alone make a struggling dependency worse. Contain it.

• Timeout every outbound call. No timeout is a bug, not a default. An un-timed call holds a connection until the OS gives up — minutes you do not have.
• Circuit breaker — stop hammering a dead dependency. Three states:
  • Closed: requests flow; count failures.
  • Open: trip at ~50% failure over a ~20-request window; reject fast for 30–60s without calling downstream.
  • Half-Open: after the cooldown, let a probe through; success → Closed, failure → Open again.
  • Critical services trip tighter (~30%); tolerant ones up to ~70%.
• Instruments (current): Opossum (Node — defaults timeout 3000ms / errorThresholdPercentage 50 / resetTimeout 30000ms), Polly 8.6.6 (.NET fluent pipelines), Resilience4j 2.3.0 (Java 17+ 2.x line; a 3.x line targets Java 21). The config matrix is in references/retry-and-resilience.md.
• Fallback / graceful degradation — when the breaker is Open, serve a stale cache, a safe default, or an honest "this feature is temporarily unavailable". Degrade; do not 500 the whole page.
• Bulkhead — isolate resource pools (separate connection pool / worker queue per dependency) so one saturated downstream cannot starve the rest. Sizing in the reference.

Step 4 — Boundaries

A boundary is where an unhandled failure is caught and converted into a contained reaction. Place one at each level that can fail independently.

React / Next.js App Router

• error.tsx is a route-segment boundary. It MUST be a Client Component ('use client') and receives { error, reset }. An error in a segment bubbles to the nearest parent error.tsx.
• error.tsx does NOT catch an error thrown in its own segment's layout.tsx or template.tsx. Those run outside the boundary — move the boundary to the parent segment to cover them.
• global-error.tsx wraps the whole app and must render its own <html> and <body> (it replaces the root layout when the root itself fails).
• Boundaries only catch errors during render. Errors in event handlers, async callbacks, setTimeout, or server-side data fetching are invisible to them — handle those with explicit try/catch + state.

"use client"; // app/dashboard/error.tsx — REQUIRED

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // Log to your telemetry sink (see observability); show the user the digest id.
  return (
    <div role="alert">
      <p>Something went wrong. Quote id {error.digest} to support.</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

The full segment-tree placement map and the global-error.tsx skeleton are in references/boundaries-and-messaging.md. Framework specifics: ../nextjs/SKILL.md.

Server and process

• Request boundary — one error handler / middleware that maps the taxonomy → HTTP status, attaches a correlation id, and emits the operator log. Every route funnels through it instead of formatting errors ad hoc.
• Process boundary — a top-level unhandledRejection / uncaughtException handler (Node) or equivalent. Log the cause chain, then exit and let the supervisor restart. A process that keeps running after an unhandled error is running corrupted.

Step 5 — Surface it

Two audiences. Never conflate them — that is how stack traces reach end users and how logs become useless.

	User message	Operator log
Goal	tell them what to do next	let you reconstruct what happened
Content	plain language, one action, a correlation id	code, cause chain, request context, structured fields
Never	stack trace, SQL, internal hostnames, PII	a swallowed/lost cause

Taxonomy → HTTP status (the in-process map; the wire envelope shape — RFC 9457 problem+json — belongs to ../api-design/SKILL.md; shipping the log to a sink belongs to ../observability/SKILL.md):

Bucket / code	Status
validation / bad input	400 / 422
unauthenticated / forbidden	401 / 403
not found	404
domain conflict (slot taken)	409
transient downstream / breaker open	503 (+ Retry-After)
programmer error / unknown	500

BAD  → alert("TypeError: cannot read 'id' of undefined")
GOOD → "We couldn't load your orders. Try again in a moment — id a1b2c3."

BAD  → 500 { "error": "ECONNREFUSED 10.0.3.12:5432" }   // leaks topology
GOOD → 503 { "code": "upstream_unavailable", "correlationId": "a1b2c3" }

More before/after rewrites and the copy contract are in references/boundaries-and-messaging.md.

Anti-patterns

Anti-pattern	Why it bites	Fix
Empty catch {} / except: pass	failure vanishes; you debug blind later	handle, or rethrow with context
Bare except: (Python)	swallows KeyboardInterrupt/SystemExit too	catch the specific type
Retry everything, including 4xx	retrying a 400 just burns budget; never succeeds	retry only the transient table
Retry a non-idempotent POST without a key	double-charges, duplicate rows	require an idempotency key first
Infinite retry, no cap or jitter	thundering herd; turns a blip into an outage	cap attempts + full jitter + budget
Leak stack trace / SQL to the user	hands attackers your internals	generic message + id; detail to the log
Expect error.tsx to catch its own segment's layout error	it runs outside the boundary; nothing catches it	move the boundary to the parent
alert(e.message) as the handler	blocks the UI, leaks internals, no recovery	render an error.tsx with reset
Catch-and-rethrow that drops cause	the root error is gone; logs are a dead end	wrap, set cause, preserve the chain
Log the error and rethrow	double-logged at every layer; noise buries signal	log at the boundary, or rethrow — not both
Swallow, then return null	callers deref null later, far from the cause	return a typed Result error
Outbound call with no timeout	one hung dependency exhausts the pool	timeout every call, then retry
One giant try around 200 lines	you cannot tell which call failed	scope try to the fallible call
Treat every error as a retryable transient	masks real bugs as "flaky"	classify first (Step 1), then react

The gate

Before claiming the failure path is handled, read your diff against the table above — those rows are the checklist. scripts/verify.sh <path> scans the working tree for the highest-signal ones. It is advisory (exit 0 with warnings); pass --strict to make any hit fail. It is heuristic — it flags, you judge.