Error Handling

An error without context is useless. Every error should answer: What, Where, Who, When, Why.

Required Attributes

Error Classification

Structured Error Type

AppError {
  Type       string   // "validation", "timeout"
  Message    string   // Human-readable
  Code       string   // For grouping
  Retryable  bool     // Can retry?
  Context    map      // Additional context
}

Capture Pattern

On error:
  → Record error on span with error.type, job.name, job.step
  → Set span status to Error
  → Log structured error with trace_id
  → Increment error counter by type/job/step

Fingerprinting

Group by: error type + message (without dynamic data) + top stack frames

Strip from fingerprints: user IDs, request IDs, timestamps, tokens

Anti-Patterns

• Swallowing errors → Log before returning default
• Missing context → Add job.name, job.step, retry.count
• PII in messages → Use structured attributes, not interpolation
• No retry context → Include attempt count and will_retry

References

• references/methodology/jtbd-for-backend.md
• references/anti-patterns.md