# Error Handling — First Principles

## 1. The Principles

### P1. Errors are Data
Errors are structured, typed, and intentional. They are values, not
exceptions to the flow of code.

### P2. Fail Loudly
Never swallow an error. Silent failure is worse than visible failure.

### P3. Fail Specifically
Generic errors are debugging enemies. "Something went wrong" is
never acceptable.

### P4. Preserve Context
Errors carry where (file, line, function), when (timestamp, request),
why (cause), and what (user-facing message).

### P5. Recoverable When Possible
Retry, fallback, or degrade. Do not crash what can be salvaged.

### P6. Unrecoverable Means Stop
When recovery is impossible or unsafe, fail fast. Do not limp on
after fatal errors.

### P7. Errors are Boundaries
Define how errors cross API, service, and module boundaries. Translation
is explicit, not accidental.

### P8. User-Facing Errors are UX
Error messages are a feature. They are written for the user, not the
developer.

### P9. Errors are Logged
Even when handled, errors are recorded. The handling is the recovery;
the log is the memory.

### P10. Errors Don't Lie
Never catch what you cannot handle. Never claim success on failure.
Never claim failure on success.