error-handling-architecture

Error Handling Architecture

Purpose

Uncaught exceptions crash servers. Leaked errors expose vulnerabilities. This skill creates a central, robust pipeline for capturing, categorizing, logging, and responding to failures without leaking sensitive data, ensuring system resilience and debugging capability.

When to use

• Setting up a new backend service
• Refactoring code with excessive uncoordinated try/catch blocks
• Standardizing API error responses across a team
• Implementing a new microservice with shared error handling

When NOT to use

• Client-side error handling (different context)
• Monitoring/alerting setup (separate concern, use Logging & Observability instead)
• Specific framework error documentation

Inputs required

• Existing backend service codebase
• Framework error handling capabilities (Express middleware, Django signals, etc.)
• Logging infrastructure setup

Workflow

1. Define Error Classes: Create base AppError class with statusCode, isOperational flag, and metadata
2. Categorize Errors: Distinguish Operational (bad input, network) from Programmer (null ptr, logic bug)
3. Centralize Middleware: Add framework-level error handler to catch ALL exceptions globally
4. Log Appropriately: Full stack for 5xx errors; metadata only for 4xx errors
5. Sanitize Output: Strip stack traces and internal details before sending to client
6. Crash on Programmer Error: Unhandled programmer errors MUST crash and restart the process
7. Test Error Paths: Verify error handling works for all failure scenarios

Rules

• MUST NEVER silently swallow exceptions (catch(e) {})
• MUST crash and restart process for unhandled Programmer Errors
• MUST standardize all HTTP error responses to RFC 7807 format
• MUST log full stack traces for 5xx errors
• MUST log only message and context for 4xx errors
• MUST sanitize all error responses (no DB details, SQL, stack traces)
• MUST NEVER throw string literals (always throw Error objects)
• MUST distinguish between Operational and Programmer errors