error-handlinglisted

# Error handling Every operation that can fail will. The design question is never whether to handle it but who needs what when it happens: the user needs a next step, the operator needs a cause, and the program needs a defined state. ## Method 1. **Sort failures into the three kinds first:** - Expected and recoverable (file missing, validation failed, network blip): handle at the call site with a specific response. - Expected and not recoverable here (config invalid, dependency down): propagate with context added; let the layer that can decide, decide. - Bugs (violated invariants, impossible states): fail fast and loud. Catching a bug and continuing corrupts data quietly, which is the worst outcome available. 2. **Never swallow.** An empty catch block, an ignored error return, a fallback that hides the cause: each converts a five-minute fix into a week of "it sometimes doesn't work". If a failure is genuinely fine, write the comment saying why it is fine; that comment is the difference between a decision and a leak. 3. **Add context at each boundary, once.** Wrap errors with what the layer was doing ("importing invoice.pdf: page 3 unreadable"), not with a restatement of the message below it. Log at the top where the error is finally handled, not at every hop; double-logged errors bury the real sequence. 4. **Retry only what deserves it:** transient failures (timeouts, temporary unavailability), with a small capped cou