Error Handling & Observability

Error Hierarchy Design

Base Error Structure

class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,        // Machine-readable: "AUTH_TOKEN_EXPIRED"
    public readonly statusCode: number,   // HTTP status: 401
    public readonly isOperational: boolean, // true = expected, false = programmer error
    public readonly context?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

Error Categories

Decision Tree: Retry vs. Fail

Is the error transient?
├── Yes → Has retry budget remaining?
│   ├── Yes → Retry with exponential backoff (base * 2^attempt + jitter)
│   └── No → Fail with "service temporarily unavailable"
└── No → Is it a client error (4xx)?
    ├── Yes → Return error to client with helpful message
    └── No → Log, alert, return generic 500

Structured Logging

Log Format (JSON)

{
  "timestamp": "ISO-8601 timestamp",
  "level": "error",
  "message": "Payment processing failed",
  "correlationId": "req-abc123",
  "service": "payment-service",
  "traceId": "trace-xyz789",
  "error": { "code": "PAYMENT_DECLINED", "message": "Card declined by issuer" }
}

Log Level Guidelines

What to NEVER Log

• Passwords, tokens, API keys, session IDs
• Full credit card numbers, SSNs, or PII
• Request/response bodies containing user data (log a hash or ID instead)
• Conversation or message content

Correlation IDs

• Generate a unique ID at the entry point (API gateway, message consumer)
• Pass it through every function call, database query, and outgoing HTTP request
• Include it in every log line and error response
• Return it to the client for support reference

Health Check Endpoints

Liveness (/health/live)

Returns 200 if the process is running. No dependency checks.

Readiness (/health/ready)

Returns 200 only if all critical dependencies are reachable:

{
  "status": "healthy",
  "checks": {
    "database": { "status": "up", "latency_ms": 12 },
    "cache": { "status": "up", "latency_ms": 3 },
    "upstream_api": { "status": "up", "latency_ms": 89 }
  }
}

Alerting Thresholds