awesome-error-standards

Error Handling Patterns

Apply consistent patterns for throwing, catching, logging, and surfacing errors so failures are predictable and debuggable without leaking internals.

When to Activate

• Implementing or refactoring error handling in an API or app
• User asks for "error handling", "how to handle errors", or "consistent errors"
• Reviewing code for proper failure handling
• Defining or documenting error contract for a service or API

Core principles

• Operational vs programmer errors — Classify first. Operational failures (network timeout, invalid input, missing record) are expected: handle, retry, or surface them. Programmer errors (undefined access, broken invariant) are bugs: crash loudly or restart the process rather than limping on with corrupted state.
• Make the bug impossible, not just fixed — A single-point fix stops one path; defense in depth stops the class. Prefer prevention left of production, in order: (1) make invalid states unrepresentable in the type system (discriminated unions, branded/opaque types) so bad states won't compile; (2) validate at the boundary; (3) runtime guards; (4) error boundaries. For a high-value invariant, guard it at more than one layer and test that bypassing an outer layer still gets caught by an inner one (deliberately skip Layer 1, verify Layer 2 catches it; confirm mocks don't silently disable a validation). Rate every fix on a ladder of rungs. Control: the mistake cannot be made (the type, the API shape, the removed option). Warning: it announces itself at the moment it is made (a compile error, a failed validation, a lint rule). Detection: it is found later (tests, monitoring, alerts). The zero rung is a comment, a doc line or "be careful"; it is not a fix and does not count. Monitoring is not prevention: an alert on a bug that already reached users has moved the bug, not stopped it. A fix report names what it made impossible and what it deliberately left possible.
• Fail at startup, not in production — Validate all required config, env vars, and connections at init and refuse to boot on failure, rather than discovering a missing value on the first request.
• Fail fast — Validate inputs and preconditions early; throw or return errors with clear messages. Do not continue with invalid state.
• Do not swallow — Avoid empty catch or broad catch that ignores; log and/or rethrow or return a result type. Propagate with context.
• Structured errors — Use a consistent shape (e.g. code, message, details) for API errors and for logs. Typed error classes or codes help callers handle by type.
• User vs developer — User-facing messages are safe and actionable; developer-facing detail (stack, internal message, request id) in logs or debug only. Never expose stack traces or SQL to end users.