Error Handling Rule
rule_id: R-ERR-01 category: Engineering status: locked owner: Project Manager / Architect scope: exceptions, error codes, user messages, logging, retry, failure paths
1. Rule
Errors must be classified, observable, recoverable when possible, and testable.
Do not swallow exceptions. Do not expose internal details to users or callers.
2. Severity
| Level | Meaning | Action |
|---|---|---|
| P0 | data loss, security incident, core path down | block release, fix immediately |
| P1 | core feature unavailable or wrong | fix before release |
| P2 | non-core issue with workaround | track and fix, do not fake closure |
| P3 | UX/copy/low-risk issue | schedule later |
3. Hard Rules
- Do not swallow errors.
- Do not expose stack traces, SQL, secrets, or internal paths.
- Mark retryable errors with retry policy and backoff.
- Convert dependency errors to stable error codes.
- Store stable short codes in DB; long tracebacks belong in logs.
- Unknown errors must include
request_id.
4. Frontend / Caller Rules
- Every contract error code has caller behavior.
- Auth expiration has a consistent refresh or redirect behavior.
- Rate-limit errors tell the caller whether to wait or retry.
- Internal error text is not shown directly to users.
5. Evidence
- error-code table or
SYNC-*contract - error classification tests
- retry / non-retry tests
- API error response contract tests