Production-Ready Error Handling System

You are a senior backend engineer who has built error handling systems for high-traffic applications processing millions of requests. You understand that good error handling is the difference between a frustrating and a delightful user experience. ## Application Context Application Type: [WEB APP / API / MOBILE BACKEND / MICROSERVICES] Tech Stack: [YOUR STACK - e.g., Node.js, Python, Go] Current Error Rate: [IF KNOWN] User-Facing: [YES / NO] Criticality: [How important is reliability? 1-10] ## Generate a Complete Error Handling Strategy: ### PART 1: ERROR CLASSIFICATION SYSTEM **Error Categories** ```typescript enum ErrorCategory { VALIDATION = "VALIDATION", // Bad input from user AUTHENTICATION = "AUTHENTICATION", // Auth failures AUTHORIZATION = "AUTHORIZATION", // Permission denied NOT_FOUND = "NOT_FOUND", // Resource doesnt exist CONFLICT = "CONFLICT", // State conflict RATE_LIMIT = "RATE_LIMIT", // Too many requests EXTERNAL_SERVICE = "EXTERNAL_SERVICE", // Third-party failure DATABASE = "DATABASE", // DB errors INTERNAL = "INTERNAL", // Unexpected errors NETWORK = "NETWORK" // Connectivity issues } ``` **For Each Category, Define:** | Category | HTTP Status | Retryable | User Message | Log Level | Alert | |----------|-------------|-----------|--------------|-----------|-------| | VALIDATION | 400 | No | Show field errors | WARN | No | | AUTHENTICATION | 401 | No | "Please log in" | INFO | After 10/min | | AUTHORIZATION | 403 | No | "No permission" | WARN | After 5/min | | NOT_FOUND | 404 | No | "Not found" | DEBUG | No | | CONFLICT | 409 | Maybe | "Already exists" | WARN | No | | RATE_LIMIT | 429 | Yes | "Slow down" | INFO | After threshold | | EXTERNAL_SERVICE | 502/503 | Yes | "Try again" | ERROR | Yes | | DATABASE | 500 | Maybe | "Try again" | ERROR | Yes | | INTERNAL | 500 | No | "We are on it" | ERROR | Yes | --- ### PART 2: ERROR CLASS IMPLEMENTATION ```typescript // Base Error Class class AppError extends Error { public readonly code: string; public readonly category: ErrorCategory; public readonly statusCode: number; public readonly isOperational: boolean; public readonly context: Record ; public readonly timestamp: Date; public readonly requestId?: string; constructor(params: { message: string; code: string; category: ErrorCategory; statusCode?: number; isOperational?: boolean; context?: Record ; cause?: Error; }) { super(params.message); this.name = this.constructor.name; this.code = params.code; this.category = params.category; this.statusCode = params.statusCode || 500; this.isOperational = params.isOperational ?? true; this.context = params.context || {}; this.timestamp = new Date(); Error.captureStackTrace(this, this.constructor); } toJSON() { return { error: { code: this.code, message: this.message, category: this.category, timestamp: this.timestamp.toISOString(), ...(process.env.NODE_ENV !== "production" && { stack: this.stack, context: this.context }) } }; } } // Specific Error Classes class ValidationError extends AppError { public readonly fields: Array ; constructor(fields: Array ) { super({ message: "Validation failed", code: "VALIDATION_ERROR", category: ErrorCategory.VALIDATION, statusCode: 400, context: { fields } }); this.fields = fields; } } // [Continue for each error type...] ``` --- ### PART 3: ERROR HANDLING MIDDLEWARE ```typescript // Express/Koa style middleware const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => { // Attach request ID for tracing const requestId = req.headers["x-request-id"] || generateRequestId(); // Determine if this is an operational error const isOperational = err instanceof AppError && err.isOperational; // Log the error appropriately if (isOperational) { logger.warn({ requestId, error: err.message, code: (err as AppError).code, context: (err as AppError).context, path: req.path, method: req.method, userId: req.user?.id }); } else { // Unexpected error - log full details logger.error({ requestId, error: err.message, stack: err.stack, path: req.path, method: req.method, body: sanitize(req.body), userId: req.user?.id }); // Alert on-call alerting.critical({ error: err, requestId, context: { path: req.path } }); } // Send appropriate response const statusCode = err instanceof AppError ? err.statusCode : 500; const response = err instanceof AppError ? err.toJSON() : { error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred", requestId } }; res.status(statusCode).json(response); }; ``` --- ### PART 4: LOGGING STRATEGY **Log Levels and When to Use:** - `DEBUG`: Development only, verbose tracing - `INFO`: Normal operations, request/response logs - `WARN`: Handled errors, degraded performance - `ERROR`: Failures requiring attention - `FATAL`: System cannot continue **Structured Log Format:** ```json { "timestamp": "2024-01-15T10:30:00.000Z", "level": "ERROR", "service": "api-gateway", "requestId": "req_abc123", "traceId": "trace_xyz789", "userId": "user_123", "error": { "code": "DATABASE_CONNECTION_FAILED", "message": "Could not connect to primary database", "category": "DATABASE", "stack": "...", "context": { "database": "users-primary", "retryAttempt": 3 } }, "request": { "method": "POST", "path": "/api/users", "duration": 5234 } } ``` --- ### PART 5: USER-FACING ERROR MESSAGES **Message Guidelines:** 1. Never expose technical details 2. Be helpful and suggest next steps 3. Use consistent tone 4. Include error reference ID **Message Templates by Category:** ```typescript const userMessages = { VALIDATION: { title: "Please check your input", template: "The following fields need attention: {fields}" }, AUTHENTICATION: { title: "Session expired", template: "Please log in again to continue.", action: { label: "Log In", url: "/login" } }, RATE_LIMIT: { title: "Slow down!", template: "You are making requests too quickly. Please wait {retryAfter} seconds.", }, EXTERNAL_SERVICE: { title: "Service temporarily unavailable", template: "We are having trouble connecting to {service}. Please try again in a few moments." }, INTERNAL: { title: "Something went wrong", template: "We encountered an unexpected error. Our team has been notified. Reference: {requestId}" } }; ``` --- ### PART 6: RETRY STRATEGIES **Exponential Backoff Implementation:** ```typescript async function withRetry ( operation: () => Promise , options: { maxRetries: number; baseDelay: number; maxDelay: number; retryableErrors: string[]; } ): Promise { let lastError: Error; for (let attempt = 0; attempt <= options.maxRetries; attempt++) { try { return await operation(); } catch (error) { lastError = error; if (!isRetryable(error, options.retryableErrors)) { throw error; } if (attempt === options.maxRetries) { throw new AppError({ message: "Max retries exceeded", code: "RETRY_EXHAUSTED", cause: error }); } const delay = Math.min( options.baseDelay * Math.pow(2, attempt) + jitter(), options.maxDelay ); await sleep(delay); } } throw lastError!; } ``` --- ### PART 7: MONITORING & ALERTING **Key Metrics to Track:** - Error rate by category - Error rate by endpoint - P50/P95/P99 response times - Retry success rate - External service failure rate **Alert Thresholds:** | Metric | Warning | Critical | |--------|---------|----------| | Error Rate | >1% | >5% | | 5xx Rate | >0.1% | >1% | | P99 Latency | >3s | >10s | | DB Errors/min | >5 | >20 | --- ### PART 8: ERROR RECOVERY PATTERNS **Circuit Breaker:** ```typescript class CircuitBreaker { private state: "CLOSED" | "OPEN" | "HALF_OPEN" = "CLOSED"; private failures = 0; private lastFailure?: Date; async execute (operation: () => Promise ): Promise { if (this.state === "OPEN") { if (this.shouldAttemptReset()) { this.state = "HALF_OPEN"; } else { throw new CircuitOpenError(); } } try { const result = await operation(); this.onSuccess(); return result; } catch (error) { this.onFailure(); throw error; } } } ``` **Fallback Strategies:** - Return cached data - Use secondary service - Return degraded response - Queue for later processing

Production-Ready Error Handling System

Prompt Content

Usage

References