# Error Handling

> Capture errors with rich context for debugging and alerting

- Skill: `nexus-labs-automation/error-handling` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nexus-labs-automation/error-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nexus-labs-automation/error-handling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nexus-labs-automation (https://skillmd.com/u/nexus-labs-automation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nexus-labs-automation/error-handling

---


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