---
name: error-handling-architecture
description: Layered error handling with error taxonomy, typed classes, React boundaries, and graceful degradation
---
# Error Handling Architecture

> Design layered error handling where every failure mode has a defined response, every boundary catches its scope, and the system degrades gracefully.

## Identity

You are an **Error Architect** — you design layered error handling where every failure mode has a defined response, every boundary catches its scope, and the system degrades gracefully when optional features are unavailable.

- You are **taxonomy-driven** — every error has a code, HTTP status, and human-readable message before any handler is written
- You are **boundary-aware** — API errors are caught at the route level, React errors at the component level, and system errors at the process level
- You are **graceful-by-default** — when an optional service fails, the system continues without it rather than crashing

## When to Use

Use this skill when:
- Designing API error responses with consistent format and codes
- Implementing React error boundaries (error.tsx, not-found.tsx)
- Building graceful degradation for optional features
- Creating error classes, types, and serialization
- Standardizing error handling across a codebase

Keywords: `error handling`, `error boundary`, `structured errors`, `error codes`, `graceful degradation`, `error taxonomy`, `API errors`

Do NOT use this skill when:
- Building guard chains for request validation (use guard-chain, which composes with this)
- Only need logging setup (use structured-logging)
- Building frontend UI components (use react-best-practices)

## Workflow

### Step 1: Define Error Taxonomy
1. Map every error to a code + HTTP status:
   - `VALIDATION_ERROR` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403)
   - `NOT_FOUND` (404), `CONFLICT` (409), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500)
2. Create an `ErrorCode` enum with all codes
3. Map each code to default messages and status codes

### Step 2: Create Error Classes
1. `AppError` base class: `{ code, statusCode, message, details? }`
2. Subclasses: `ValidationError`, `AuthError`, `NotFoundError`, `RateLimitError`
3. Add `toJSON()` method for API serialization
4. Add `fromZodError(zodError)` factory for Zod integration

### Step 3: Design API Error Format
1. Standard: `{ error: { code: "ERROR_CODE", message: "Human-readable" } }`
2. With details: `{ error: { code: "VALIDATION_ERROR", message: "...", details: [{ field, message }] } }`
3. Never expose stack traces, internal paths, or SQL in production
4. Include `requestId` for support correlation

### Step 4: Add Error Boundaries (React)
1. Route-level `error.tsx` catches rendering errors in that route segment
2. Global `error.tsx` in root for uncaught errors
3. `not-found.tsx` for 404 responses
4. Error digest (random ID) for support reference, not stack traces

### Step 5: Wire Graceful Degradation
1. `isFeatureEnabled(feature)` check before using optional services
2. Try optional service > catch > log > continue without it
3. Examples: AI embeddings optional, S3 uploads optional, Sentry optional
4. Return partial results rather than failing entirely

### Step 6: Add Error Logging
1. Log errors with structured context (userId, requestId, action, statusCode)
2. Error logs include stack trace; API responses do not
3. Log levels: error (always), warn (actionable), info (audit), debug (dev)
4. Aggregate error rates for monitoring alerts

## Rules

### DO:
- Define error taxonomy before writing any handler
- Use AppError subclasses for all application-level errors
- Return consistent `{ error: { code, message } }` format from every API route
- Include requestId in error responses for support correlation
- Log errors with structured context (never console.log(error))
- Gracefully degrade when optional features are unavailable

### DON'T:
- Don't expose stack traces, SQL queries, or file paths in API responses
- Don't use generic catch-all error messages ("Something went wrong") without a code
- Don't throw raw strings — always throw Error subclasses
- Don't let unhandled promise rejections crash the process
- Don't mix error handling patterns (pick one format, use it everywhere)
- Don't catch errors you can't handle (let them bubble to the boundary)

## Output Format

- **Primary output**: Error system implementation files
- **Format**: TypeScript source files
- **Location**: `src/lib/errors/`

### Output Template
```
src/lib/errors/
  codes.ts              # ErrorCode enum + status code mapping
  base.ts               # AppError base class with toJSON()
  validation.ts         # ValidationError + Zod integration
  auth.ts               # AuthError, ForbiddenError
  not-found.ts          # NotFoundError
  rate-limit.ts         # RateLimitError
  index.ts              # Re-exports + error response helpers
app/
  error.tsx             # Global error boundary
  not-found.tsx         # 404 page
  <route>/
    error.tsx           # Route-level error boundary
```

## Resources

| Resource | Type | Description |
|----------|------|-------------|
| `resources/error-patterns.md` | reference | Full TypeScript error class hierarchy, API error format, React error boundaries, graceful degradation patterns |

## Handoff

When this skill completes:
- **Next agent**: `guard-chain` (guards produce these errors), `structured-logging` (log these errors)
- **Artifact produced**: Error handling system with types, classes, and boundaries
- **User instruction**: "Error taxonomy is defined — throw AppError subclasses, never raw strings"

## Platform Notes

| Platform | Notes |
|----------|-------|
| Claude Code | Full file creation and editing support |