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

• 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.

Work Process