# error-handling

> Capture errors with rich context for debugging and alerting

- Author: Caleb Davis
- Repository: nexus-labs-automation/backend-observability
- Version: 20251226173014
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/nexus-labs-automation/backend-observability
- Web: https://mule.run/skillshub/@@nexus-labs-automation/backend-observability~error-handling:20251226173014

---

---
name: error-handling
description: "Capture errors with rich context for debugging and alerting"
triggers:
  - "error tracking"
  - "exception monitoring"
  - "error context"
  - "structured errors"
priority: 1
---

# Error Handling

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

## Required Attributes

| Attribute | Example | Required |
|-----------|---------|----------|
| `error.type` | ValidationError, TimeoutError | Yes |
| `error.message` | "Invalid email format" | Yes |
| `exception.stacktrace` | Full stack trace | Yes |
| `job.name` | checkout, signup | Recommended |
| `job.step` | payment, validation | Recommended |

## Error Classification

| Level | Status | Action |
|-------|--------|--------|
| Critical | 500 | Page immediately |
| Error | 500 | Alert, investigate |
| Warning | 4xx | Track, batch review |
| Info | - | Log only |

## 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`