error-handling-patterns

Exceptions handle unexpected errors that break normal flow; the Result pattern handles expected business failures like validation or 'user not found' without throwing. Use exceptions for truly exceptional conditions and Result pattern for anticipated domain-level failures.

Define domain-specific and infrastructure-specific exception classes per bounded context instead of base error classes. Include rich context data—error codes, details, and domain state—so handlers can recover or log precisely without guessing what failed.

Validate at entry points using tools like Zod to catch malformed data before it enters your domain. Separate input validation from domain validation; domain validation happens within entities and enforces business rules after structure is verified.

Retry logic handles transient failures by attempting requests again with backoff. Circuit breakers stop sending requests when services fail repeatedly, failing fast and protecting downstream systems from cascading failures.

Yes. Use context-specific error types in repositories, use cases, and controllers. Clean Architecture and dependency injection containers isolate error handling per layer so each layer throws or catches appropriate exceptions for its responsibility.

Generic errors lose context needed for recovery; return codes require callers to know magic numbers. Rich custom exceptions with context data and clear semantics let handlers make better decisions and enable better logging and monitoring.