Error Handling — Notes

Rules of thumb

1. Surface errors at API boundaries. Internal helpers can throw; public APIs return typed errors.
2. Distinguish recoverable from bug. NullPointerException ≠ "card declined".
3. Preserve causes. Log + wrap with context, but don't lose the original.
4. One mapper at the edge. Map domain errors to HTTP/gRPC statuses in one place.
5. No silent retries. Every retry decision is logged and observable.

Naming

• NotFoundException, ValidationException, ConflictException — domain layer.
• OrderRepositoryException — infra layer.
• IllegalStateException, IllegalArgumentException — bug indicators.

Test what you ignore

For every error path, write at least one negative test. The hidden bugs hide there.

Refs

• Effective Java — Items 70–77 (exceptions).
• Rust book — "Error handling" chapter.
• Joe Duffy: "The Error Model" (Midori retrospective).
• Joel Spolsky: "Exceptions are bad" — read with an open mind.