mav-bp-error-handling

Error Handling Standards

Maverick's hard rules for intentional, typed, resilient error handling.

Maverick's Rules

• Never swallow silently — every catch handles, logs, or re-throws. An empty catch is a bug.
• Catch at boundaries only — throw/return from low-level code, catch at service boundaries and the outermost handler. Catching at every layer duplicates logging and loses stack traces. No catch-and-re-throw without adding context.
• Typed errors — every application error carries type (machine-readable classification), message, context (structured metadata), and cause (wrapped original). Never throw new Error("failed").
• Log-level mapping: 4xx → warn, 5xx → error — client errors are expected (track volume, no alert unless it spikes); server errors require investigation and alert when persistent. Log levels and alerting per mav-bp-operability.
• Retry policy — 3 attempts max (1 initial + 2 retries) unless configured otherwise; exponential backoff (base * 2^attempt) with jitter. Retry only transient failures: timeouts, 429, 502, 503, 504. Never retry 400/401/403/404 or non-idempotent operations without idempotency keys.
• Never expose internals to clients — no stack traces, SQL/database messages, file paths, internal service names, or dependency versions in responses. Return a safe message, a machine-readable error type, and a request/correlation ID.
• Critical paths must not depend on non-critical services — degrade the feature (visibly, and log/alert on degraded mode) rather than crash. Frontend: error boundaries around major UI sections with fallback UI and error reporting.
• Fail fast on unrecoverable errors — configuration failures, corruption, programming errors: crash immediately with a clear message; do not attempt recovery.

Project Implementation Lookup

Check for docs/maverick/skills/error-handling/SKILL.md. If present, read it — it wins on specifics (library, config, conventions). If missing, proceed with these standards and note the gap in your summary.