Error Handling
Core Principles
- Use the Result pattern for expected failures — Don't throw exceptions for things like "order not found" or "validation failed". These are expected outcomes, not exceptional conditions. See ADR-002.
- Reserve exceptions for unexpected failures — Database connection lost, null reference bugs, network timeouts — these are truly exceptional and should propagate to the global handler.
- Every API error returns ProblemDetails — RFC 9457 is the standard. Every error response has
type,title,status,detail, and optionallyerrors. - Validate at the boundary — Validate incoming requests at the API layer, not deep inside business logic.
Patterns
Result Pattern
A simple, generic result type that carries either a value or errors.
Result to ProblemDetails Mapping
Global Exception Handler
Catches unexpected exceptions and converts them to ProblemDetails. For the modern IExceptionHandler approach (preferred), see knowledge/common-infrastructure.md. The inline lambda below works for simple cases:
FluentValidation with Endpoint Filters
Typed Error Results
For richer error handling, use typed error enums or error objects.


