Code Quality
Error Handling Design

Error Handling Design

Non-Negotiables

  1. No swallowed errors. Silence is sabotage.
  2. Errors must be diagnosable. Every error needs context and a path to action.
  3. External errors must be stable. Clients depend on contracts.
  4. Security beats verbosity. Never leak secrets or internal details.

Minimum Requirements (Industry Standard Baseline)

Error Taxonomy

Define and enforce categories (examples):

  • Validation (client fix)
  • Authentication/Authorization (client fix)
  • Not Found (client fix)
  • Conflict (client fix / concurrency)
  • Dependency Failure (server/operator action)
  • Internal (server action)

Error Contract (API)

Return a consistent shape:

  • code: stable machine-readable code
  • message: human-readable summary
  • details: optional structured fields (safe to expose)
  • trace_id: correlation id for support

Boundaries

  • Catch exceptions at boundaries only (HTTP handler, job entrypoint, message consumer).
  • Inside core logic: prefer returning typed results or throwing domain errors.

Retry Policy

  • Retries are for transient failures only.
  • Always use:
    • max attempts
    • exponential backoff
    • jitter
    • circuit breakers where applicable

Observability

  • Every error path must:
    • log once (structured)
    • emit metrics (error rate)
    • preserve stack traces internally

References

API DesignLogging Standard