error-handling-patterns

Error handling has one purpose: when something goes wrong, the right party finds out, with enough context to act, and the system stays in a known state. Every pattern below is judged by that.

First decision: expected outcome or bug?

• Expected outcomes (not found, validation failed, permission denied, rate limited, conflict) are part of the function's contract. Represent them in the type: a result type, a discriminated union, a documented typed error. Callers handle them.
• Bugs and infrastructure failures (null where impossible, invariant broken, database down, out of memory) are exceptions. They propagate to a boundary that logs them and fails the operation; code in between does not catch them.

Mixing the two (throwing for "not found", or returning null for "database down") produces both noisy logs and silent failures.

Represent errors with types

• Base error class per domain (AppError with code, httpStatus, isOperational), subclasses for categories (NotFoundError, ValidationError, ConflictError, UpstreamError). One place maps code to status and to user message.
• Or a result type (Result<T, E> / Either) for expected outcomes in functional codebases; then errors are values, exhaustively matched, and never forgotten. Do not use both styles in one module.
• Errors carry structured context: the ids involved, the operation, the upstream status. Not the user's secrets, not whole request bodies.

Where to catch

Catch at boundaries: the HTTP handler, the CLI entry, the job runner, the message consumer, the top of a background task. There, translate to the boundary's vocabulary (status code, exit code, ack/nack), log once with full context, and stop.

In between, catch only to add context and rethrow (throw new UpstreamError("payments: charge failed", { cause: err, orderId })) or to handle an expected outcome you can actually resolve (retry, fallback with a documented consequence, default that is semantically correct).