Error Handling Resilience Audit

This document is a focused technical audit of error handling and resilience for an API/Node.js (Express) application. It condenses a broader quality review into concrete findings, prioritized remediation, and precise, drop-in code fixes you can apply quickly to reduce risk and improve uptime.

Purpose: identify gaps in error handling consistency, categorization, async handling, recovery patterns, and error information exposure — then provide targeted code snippets and configuration changes that are minimal to integrate. Example prompt used to drive the audit (trimmed for clarity):

4. ERROR RECOVERY
– Graceful degradation
– Retry mechanisms
– Circuit breakers
– Fallback strategies

5. ERROR INFORMATION
– Development vs production error details
– Stack trace exposure
– Error logging completeness
– User-friendly error messages

Identify error handling gaps and provide improved implementation.

## Provide:

A structured finding report

A scale of 1/10 on how important each finding is

Remediation: precise code-level fix or config change (snippets welcome)

## Constraints & style:

Be concrete and cite exact code locations and identifiers.
Prefer minimal, drop-in fix snippets over prose.
Do not invent files or functions that aren't present; if context is missing, mark as Unable to verify and say what code would prove it.
Write this into a markdown file and place it in the audits/ folder.

Evaluation checklist used during the audit:

ERROR HANDLING CONSISTENCY
- Centralized error handler?
- Uniform response formats?
- Custom error classes vs generic errors?
ERROR CATEGORIES
- Validation (400), Authentication (401), Authorization (403), Not found (404), Server (500), Rate limit (429), Conflict (409)
ASYNC ERROR HANDLING
- Unhandled promise rejections
- Async middleware wrapper usage
- Callback & EventEmitter error handling
ERROR RECOVERY
- Graceful degradation
- Retry mechanisms
- Circuit breakers
- Fallback strategies
ERROR INFORMATION
- Dev vs Prod error detail
- Stack trace exposure
- Error logging completeness
- User-friendly error messages

Executive summary

Status: ❌ CRITICAL DEFICIENCIES IDENTIFIED
Overall Score: 3.5 / 10 The Express Login Demo exposes several critical error-handling and resilience gaps. Primary risks include lack of centralized error handling, leakage of sensitive information in logs/responses, missing global handlers for unhandled rejections/uncaught exceptions, and no recovery patterns (retries/circuit breakers/fallbacks). Most critical security-related fixes are small and can be implemented in ~1 week. Reaching full resilience maturity (observability, circuit breakers, graceful degradation) is estimated at 2–3 months. Critical findings overview:

Category	Score	Status	Key issue
Error Handling Consistency	2/10	❌ FAIL	No centralized error middleware; routes return inconsistent shapes
Error Categories	4/10	⚠️ PARTIAL	Several HTTP categories (403, 409, 429) missing or used inconsistently
Async Error Handling	3/10	❌ FAIL	Missing `unhandledRejection`/`uncaughtException` and async wrapper usage
Error Recovery	1/10	❌ FAIL	No retry or circuit breaker patterns; high risk of cascading failures
Error Information	4/10	⚠️ PARTIAL	Stack traces and DB errors appear in logs/responses; no structured logging

1. ERROR HANDLING CONSISTENCY

Finding

No centralized error middleware is plugged in after routes.
Route handlers return heterogeneous response shapes and sometimes directly call console.error.
No standard error object or machine-readable error payload.

Remediation — minimal, drop-in utilities

Standardized error response object:

// utils/errorResponse.js
class ErrorResponse {
  constructor(message, statusCode = 500, details = null) {
    this.message = message;
    this.statusCode = statusCode;
    this.details = details;
  }

  toJSON() {
    const payload = { error: this.message };
    if (this.details) payload.details = this.details;
    return payload;
  }
}

module.exports = ErrorResponse;

Central HTTP error class:

// utils/httpErrors.js
class HTTPError extends Error {
  constructor(message, statusCode = 500, details = null) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.details = details;
    Error.captureStackTrace(this, this.constructor);
  }
}

module.exports = HTTPError;

Centralized Express error-handling middleware (register after all routes):

// middleware/errorHandler.js
const HTTPError = require('../utils/httpErrors');
const logger = require('../utils/logger'); // see logger snippet below

const sanitizeError = (err) => {
  // Limit what is returned to the client
  const payload = {
    message: err.message || 'Internal Server Error',
  };
  if (err.code) payload.code = err.code;
  return payload;
};

const errorHandler = (err, req, res, next) => {
  const statusCode = err.statusCode || 500;

  // Server-side logging of full error (structured)
  logger.error('Request error', { error: err });

  // Client response: minimal info in production, expanded in development
  const responseBody = sanitizeError(err);
  if (process.env.NODE_ENV === 'development') {
    responseBody.stack = err.stack;
    responseBody.details = err.details || null;
  }

  res.status(statusCode).json(responseBody);
};

module.exports = errorHandler;

Integration tip: Replace ad-hoc responses with next(new HTTPError('message', 400)). Ensure app.use(errorHandler) is the final middleware.

2. ERROR CATEGORIES

Finding

Routes occasionally use 400/401/500, but 403, 404, 409, and 429 are inconsistent or missing.
Lack of helpers leads to human error and inconsistent client behavior.

Remediation — helper factory for consistent HTTP errors

// utils/httpHelpers.js
const HTTPError = require('./httpErrors');

const BadRequest = (msg, details) => new HTTPError(msg || 'Bad Request', 400, details);
const Unauthorized = (msg) => new HTTPError(msg || 'Unauthorized', 401);
const Forbidden = (msg) => new HTTPError(msg || 'Forbidden', 403);
const NotFound = (msg) => new HTTPError(msg || 'Not Found', 404);
const Conflict = (msg) => new HTTPError(msg || 'Conflict', 409);
const TooManyRequests = (msg) => new HTTPError(msg || 'Too Many Requests', 429);
const ServiceUnavailable = (msg) => new HTTPError(msg || 'Service Unavailable', 503);

module.exports = { BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequests, ServiceUnavailable };

Usage example:

const { NotFound, Forbidden } = require('../utils/httpHelpers');

if (!resource) return next(NotFound('User not found'));
if (!canAccess(user, resource)) return next(Forbidden('Insufficient permissions'));

3. ASYNC ERROR HANDLING

Findings

No global process.on('unhandledRejection') or process.on('uncaughtException') handlers.
Route handlers use manual try/catch or nothing; no async wrapper in place.
Potential for unhandled promise rejections to crash the process unpredictably.

Remediation

Add global process handlers (put these near server startup, before app.listen()):

// server.js (or index.js) — add before app.listen(...)
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
  // Perform graceful shutdown if you have an http server instance:
  if (server && server.close) {
    server.close(() => process.exit(1));
  } else {
    process.exit(1);
  }
});

process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  // Best practice: log and restart the process (managed by a supervisor like PM2 or k8s)
  process.exit(1);
});

Async wrapper middleware (very small, drop-in):

// middleware/asyncWrapper.js
module.exports = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

Usage:

// routes/auth.js
const asyncWrapper = require('../middleware/asyncWrapper');

router.post('/login', asyncWrapper(async (req, res) => {
  const user = await authService.authenticate(req.body);
  res.json({ user });
}));

This pattern ensures thrown errors are forwarded to the centralized errorHandler.

4. ERROR RECOVERY

Findings

No retry logic for transient failures (database, network).
No circuit breaker to prevent rapid cascading failures to dependencies.
No fallback or graceful degradation for non-critical features.

Remediation — small, practical utilities

Simple retry helper with exponential backoff:

// utils/retry.js
const delay = (ms) => new Promise((r) => setTimeout(r, ms));

const retry = async (operation, maxAttempts = 3, initialDelay = 500) => {
  let lastError;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (err) {
      lastError = err;
      if (attempt < maxAttempts) {
        const backoff = initialDelay * 2 ** (attempt - 1);
        await delay(backoff);
      }
    }
  }
  throw lastError;
};

module.exports = retry;

Example usage with Mongoose:

const retry = require('./utils/retry');
await retry(() => mongoose.connect(uri, opts), 5, 1000);

Lightweight circuit breaker to protect fragile external calls:

// utils/circuitBreaker.js
class CircuitBreaker {
  constructor({ failureThreshold = 5, resetTimeout = 60000 } = {}) {
    this.failureThreshold = failureThreshold;
    this.resetTimeout = resetTimeout;
    this.failureCount = 0;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
    this.nextAttempt = Date.now();
  }

  async fire(action) {
    if (this.state === 'OPEN') {
      if (Date.now() > this.nextAttempt) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('CircuitBreakerOpen');
      }
    }

    try {
      const result = await action();
      this.success();
      return result;
    } catch (err) {
      this.fail();
      throw err;
    }
  }

  success() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  fail() {
    this.failureCount += 1;
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.resetTimeout;
    }
  }
}

module.exports = CircuitBreaker;

Apply CircuitBreaker.fire(() => remoteCall()) for DB/third-party services. For production-grade resilience, consider libraries like opossum which offer metrics and event hooks.

5. ERROR INFORMATION (LOGGING & EXPOSURE)

Findings

Console logging of full error objects and DB details leaks secrets.
No structured logging; logs are inconsistent and hard to search.
Stack traces are returned to clients in production in some cases.

Remediation — structured logger + sanitization

Replace console.log/console.error with a structured logger like winston:

// utils/logger.js
const { createLogger, format, transports } = require('winston');

const logger = createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: format.combine(
    format.timestamp(),
    format.errors({ stack: true }),
    format.splat(),
    format.json()
  ),
  transports: [
    new transports.Console(),
    // Add file or centralized transports for production:
    // new transports.File({ filename: 'logs/error.log', level: 'error' })
  ],
});

module.exports = logger;

Sanitize logs and responses: ensure sanitizeError strips fields like password, connectionString, ssn before logging or returning to clients.
Environment-specific responses: only include stack traces in development. In production, return minimal messages and include a reference ID to correlate logs:

// Example production response
{
  "error": "Service Unavailable",
  "reference": "err-20261020-abcdef"
}

Record the reference in structured logs for post-mortem.

PRIORITY REMEDIATION PLAN

Immediate (Week 1) — Critical

Add and register centralized errorHandler middleware; replace ad-hoc responses.
Add global unhandledRejection / uncaughtException handlers and ensure server.close() is used for graceful shutdown.
Replace console with structured logger and add basic sanitization rules.

Short-term (Month 1) 4. Add asyncWrapper for routes and refactor handlers to use it. 5. Adopt standardized HTTP error helpers and ensure all routes use them. 6. Use retry helper for transient DB/network operations. Medium-term (Month 2–3) 7. Integrate circuit breakers around external dependencies. 8. Implement graceful degradation and fallback strategies for non-critical features. 9. Add rate limiting (return 429) and monitoring/alerts tied to error thresholds and circuit breaker events.

Prioritize fixes that remove secret leakage from logs and add global rejection handlers — these reduce attack surface and prevent abrupt crashes.

SECURITY IMPACT & READINESS

Production Readiness: NOT READY After applying prioritized fixes:

Error information disclosure: LOW RISK
Application stability: MEDIUM → HIGH (once retries/circuit breakers are in place)
Debugging & observability: SIGNIFICANTLY IMPROVED (with structured logging and reference IDs)

Estimated time:

Critical fixes: 2–3 weeks (depending on testing and rollout strategy)
Full resilience (monitoring, circuit breakers, graceful degradation): 2–3 months

Notes on verification

If repository snapshot lacks specific files or code locations, mark the finding as “Unable to verify” and list the exact evidence that would validate the finding (e.g., “routes/auth.js contains console.error(err) with full err object logged” or “no process.on('unhandledRejection') handler present in server startup file”).
Prefer minimal, drop-in snippets to make integration easier.
Keep a checklist of files changed and tests added to verify behavior (unit tests for asyncWrapper, integration tests for retry and circuitBreaker).

The full technical audit (structured findings, importance scores, and all suggested code snippets) was written to audits/ERROR_HANDLING_COMPREHENSIVE_REVIEW.md per the audit prompt. Implementing the above will materially improve resilience, security, and production readiness.

Introduction

Getting Started with Claude Code

Working with Claude Code

Code Review with Claude Code

Security Auditing with Claude Code

Advanced Features

Error Handling Resilience Audit

Executive summary

1. ERROR HANDLING CONSISTENCY

2. ERROR CATEGORIES

3. ASYNC ERROR HANDLING

4. ERROR RECOVERY

5. ERROR INFORMATION (LOGGING & EXPOSURE)

PRIORITY REMEDIATION PLAN

SECURITY IMPACT & READINESS

Notes on verification

Watch Video

​Executive summary

​1. ERROR HANDLING CONSISTENCY

​2. ERROR CATEGORIES

​3. ASYNC ERROR HANDLING

​4. ERROR RECOVERY

​5. ERROR INFORMATION (LOGGING & EXPOSURE)

​PRIORITY REMEDIATION PLAN

​SECURITY IMPACT & READINESS

​Notes on verification

Watch Video

Executive summary

1. ERROR HANDLING CONSISTENCY

2. ERROR CATEGORIES

3. ASYNC ERROR HANDLING

4. ERROR RECOVERY

5. ERROR INFORMATION (LOGGING & EXPOSURE)

PRIORITY REMEDIATION PLAN

SECURITY IMPACT & READINESS

Notes on verification