Part 5: Error Handling and Validation

The Production Incident

At 2 AM, my phone buzzed—production alert. Our payment API was down. I opened CloudWatch logs and saw:

TypeError: Cannot read property 'amount' of undefined
TypeError: Cannot read property 'amount' of undefined
TypeError: Cannot read property 'amount' of undefined
...500 errors in 2 minutes

The bug? A client sent malformed JSON. My code assumed the amount field existed. No validation, no null checks, no error handling. The entire payment service crashed.

After 30 minutes of scrambling, I added validation and proper error handling. The service restarted. Incident resolved.

That night taught me: validation and error handling aren't optional—they're what separates hobby projects from production systems.

This article shares the error handling patterns that have kept my APIs running 24/7.

Input Validation

Why Validate?

Security: Prevent SQL injection, XSS attacks Stability: Prevent crashes from unexpected input User experience: Clear error messages Data integrity: Ensure database consistency

Validation Libraries

I use Zod for TypeScript—runtime validation with type inference.

npm install zod

Schema Definition

// src/schemas/user-schema.ts
import { z } from 'zod';

export const CreateUserSchema = z.object({
  email: z.string()
    .email('Invalid email format')
    .toLowerCase()
    .trim(),
  
  password: z.string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Password must contain uppercase letter')
    .regex(/[a-z]/, 'Password must contain lowercase letter')
    .regex(/[0-9]/, 'Password must contain number'),
  
  name: z.string()
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name cannot exceed 100 characters')
    .trim(),
  
  age: z.number()
    .int('Age must be an integer')
    .min(18, 'Must be at least 18 years old')
    .max(120, 'Invalid age')
    .optional(),
  
  role: z.enum(['user', 'admin', 'manager'])
    .default('user'),
});

export const UpdateUserSchema = z.object({
  email: z.string()
    .email('Invalid email format')
    .optional(),
  
  name: z.string()
    .min(2, 'Name must be at least 2 characters')
    .max(100, 'Name cannot exceed 100 characters')
    .trim()
    .optional(),
  
  age: z.number()
    .int('Age must be an integer')
    .min(18, 'Must be at least 18 years old')
    .max(120, 'Invalid age')
    .optional(),
});

export const LoginSchema = z.object({
  email: z.string()
    .email('Invalid email format'),
  
  password: z.string()
    .min(1, 'Password is required'),
});

// Product schemas
export const CreateProductSchema = z.object({
  name: z.string()
    .min(1, 'Product name is required')
    .max(200, 'Product name too long'),
  
  description: z.string()
    .max(1000, 'Description too long')
    .optional(),
  
  price: z.number()
    .positive('Price must be positive')
    .multipleOf(0.01, 'Price must have at most 2 decimal places'),
  
  stock: z.number()
    .int('Stock must be an integer')
    .min(0, 'Stock cannot be negative'),
  
  categoryId: z.string()
    .uuid('Invalid category ID'),
  
  tags: z.array(z.string())
    .max(10, 'Maximum 10 tags allowed')
    .optional(),
});

// Query parameter schema
export const ProductQuerySchema = z.object({
  page: z.string()
    .transform(Number)
    .pipe(z.number().int().positive())
    .default('1'),
  
  limit: z.string()
    .transform(Number)
    .pipe(z.number().int().min(1).max(100))
    .default('20'),
  
  sortBy: z.enum(['name', 'price', 'createdAt'])
    .default('createdAt'),
  
  order: z.enum(['asc', 'desc'])
    .default('desc'),
  
  category: z.string().optional(),
  
  minPrice: z.string()
    .transform(Number)
    .pipe(z.number().positive())
    .optional(),
  
  maxPrice: z.string()
    .transform(Number)
    .pipe(z.number().positive())
    .optional(),
});

// Type inference
export type CreateUserDto = z.infer<typeof CreateUserSchema>;
export type UpdateUserDto = z.infer<typeof UpdateUserSchema>;
export type LoginDto = z.infer<typeof LoginSchema>;
export type CreateProductDto = z.infer<typeof CreateProductSchema>;
export type ProductQuery = z.infer<typeof ProductQuerySchema>;

Validation Middleware

// src/middleware/validation-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { ZodSchema, ZodError } from 'zod';
import { ResponseFormatter } from '../utils/response-formatter';

export class ValidationMiddleware {
  static validateBody(schema: ZodSchema) {
    return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
      try {
        const validated = await schema.parseAsync(req.body);
        req.body = validated; // Replace with validated data
        next();
      } catch (error) {
        if (error instanceof ZodError) {
          const errors = error.errors.map(err => ({
            field: err.path.join('.'),
            message: err.message,
          }));
          
          res.status(422).json(
            ResponseFormatter.error('Validation failed', errors)
          );
          return;
        }
        
        res.status(500).json(
          ResponseFormatter.error('Validation error')
        );
      }
    };
  }

  static validateQuery(schema: ZodSchema) {
    return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
      try {
        const validated = await schema.parseAsync(req.query);
        req.query = validated as any; // Replace with validated data
        next();
      } catch (error) {
        if (error instanceof ZodError) {
          const errors = error.errors.map(err => ({
            field: err.path.join('.'),
            message: err.message,
          }));
          
          res.status(422).json(
            ResponseFormatter.error('Invalid query parameters', errors)
          );
          return;
        }
        
        res.status(500).json(
          ResponseFormatter.error('Validation error')
        );
      }
    };
  }

  static validateParams(schema: ZodSchema) {
    return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
      try {
        const validated = await schema.parseAsync(req.params);
        req.params = validated as any;
        next();
      } catch (error) {
        if (error instanceof ZodError) {
          const errors = error.errors.map(err => ({
            field: err.path.join('.'),
            message: err.message,
          }));
          
          res.status(422).json(
            ResponseFormatter.error('Invalid URL parameters', errors)
          );
          return;
        }
        
        res.status(500).json(
          ResponseFormatter.error('Validation error')
        );
      }
    };
  }
}

Using Validation in Routes

// src/routes/user-routes.ts
import { Router } from 'express';
import { UserController } from '../controllers/user-controller';
import { ValidationMiddleware } from '../middleware/validation-middleware';
import { CreateUserSchema, UpdateUserSchema } from '../schemas/user-schema';

export class UserRoutes {
  static setup(controller: UserController): Router {
    const router = Router();

    // Validate body on POST
    router.post(
      '/',
      ValidationMiddleware.validateBody(CreateUserSchema),
      controller.createUser.bind(controller)
    );

    // Validate body on PATCH
    router.patch(
      '/:id',
      ValidationMiddleware.validateBody(UpdateUserSchema),
      controller.updateUser.bind(controller)
    );

    return router;
  }
}

// src/routes/product-routes.ts
import { ProductQuerySchema, CreateProductSchema } from '../schemas/product-schema';

export class ProductRoutes {
  static setup(controller: ProductController): Router {
    const router = Router();

    // Validate query parameters
    router.get(
      '/',
      ValidationMiddleware.validateQuery(ProductQuerySchema),
      controller.getProducts.bind(controller)
    );

    // Validate request body
    router.post(
      '/',
      ValidationMiddleware.validateBody(CreateProductSchema),
      controller.createProduct.bind(controller)
    );

    return router;
  }
}

Error Classification

Custom Error Classes

// src/errors/custom-errors.ts
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number,
    public isOperational: boolean = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
    Error.captureStackTrace(this, this.constructor);
  }
}

export class ValidationError extends AppError {
  constructor(message: string, public errors?: any[]) {
    super(message, 422);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404);
  }
}

export class UnauthorizedError extends AppError {
  constructor(message: string = 'Authentication required') {
    super(message, 401);
  }
}

export class ForbiddenError extends AppError {
  constructor(message: string = 'Access denied') {
    super(message, 403);
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409);
  }
}

export class BadRequestError extends AppError {
  constructor(message: string) {
    super(message, 400);
  }
}

export class DatabaseError extends AppError {
  constructor(message: string = 'Database operation failed') {
    super(message, 500, false); // Not operational
  }
}

export class ExternalServiceError extends AppError {
  constructor(service: string, message?: string) {
    super(message || `${service} service unavailable`, 503);
  }
}

Using Custom Errors

// src/services/user-service.ts
import {
  NotFoundError,
  ConflictError,
  ValidationError,
} from '../errors/custom-errors';

export class UserService {
  async createUser(userData: CreateUserDto): Promise<User> {
    // Check for existing user
    const existing = await this.userRepository.findByEmail(userData.email);
    if (existing) {
      throw new ConflictError('Email already registered');
    }

    // Create user
    try {
      return await this.userRepository.create(userData);
    } catch (error) {
      throw new DatabaseError('Failed to create user');
    }
  }

  async getUserById(id: string): Promise<User> {
    const user = await this.userRepository.findById(id);
    
    if (!user) {
      throw new NotFoundError('User');
    }
    
    return user;
  }

  async updateUser(id: string, updates: UpdateUserDto): Promise<User> {
    const user = await this.userRepository.findById(id);
    
    if (!user) {
      throw new NotFoundError('User');
    }

    // Check email uniqueness if being updated
    if (updates.email && updates.email !== user.email) {
      const existing = await this.userRepository.findByEmail(updates.email);
      if (existing) {
        throw new ConflictError('Email already in use');
      }
    }

    return this.userRepository.update(id, updates);
  }
}

Global Error Handler

// src/middleware/error-handler.ts
import { Request, Response, NextFunction } from 'express';
import { AppError, ValidationError } from '../errors/custom-errors';
import { ResponseFormatter } from '../utils/response-formatter';

export class ErrorHandler {
  static handle(
    err: Error,
    req: Request,
    res: Response,
    next: NextFunction
  ): void {
    // Log error
    console.error('Error:', {
      message: err.message,
      stack: err.stack,
      path: req.path,
      method: req.method,
      body: req.body,
    });

    // Operational errors (known errors)
    if (err instanceof AppError && err.isOperational) {
      if (err instanceof ValidationError) {
        res.status(err.statusCode).json(
          ResponseFormatter.error(err.message, err.errors)
        );
        return;
      }

      res.status(err.statusCode).json(
        ResponseFormatter.error(err.message)
      );
      return;
    }

    // Database errors
    if (err.message.includes('ECONNREFUSED')) {
      res.status(503).json(
        ResponseFormatter.error('Database temporarily unavailable')
      );
      return;
    }

    if (err.message.includes('duplicate key')) {
      res.status(409).json(
        ResponseFormatter.error('Resource already exists')
      );
      return;
    }

    // JWT errors
    if (err.name === 'JsonWebTokenError') {
      res.status(401).json(
        ResponseFormatter.error('Invalid token')
      );
      return;
    }

    if (err.name === 'TokenExpiredError') {
      res.status(401).json(
        ResponseFormatter.error('Token expired')
      );
      return;
    }

    // Multer errors (file upload)
    if (err.name === 'MulterError') {
      res.status(400).json(
        ResponseFormatter.error(`File upload error: ${err.message}`)
      );
      return;
    }

    // Unknown errors (hide details in production)
    if (process.env.NODE_ENV === 'production') {
      res.status(500).json(
        ResponseFormatter.error('Internal server error')
      );
    } else {
      res.status(500).json({
        success: false,
        error: 'Internal server error',
        message: err.message,
        stack: err.stack,
      });
    }
  }

  // Catch async errors
  static catchAsync(fn: Function) {
    return (req: Request, res: Response, next: NextFunction) => {
      Promise.resolve(fn(req, res, next)).catch(next);
    };
  }
}

Using Error Handler

// src/app.ts
import { ErrorHandler } from './middleware/error-handler';

export class App {
  private setupErrorHandling(): void {
    // 404 handler (no route matched)
    this.app.use((req, res) => {
      res.status(404).json(
        ResponseFormatter.error(`Route ${req.path} not found`)
      );
    });

    // Global error handler (must be last)
    this.app.use(ErrorHandler.handle);
  }
}

// src/controllers/user-controller.ts
export class UserController {
  // Manually wrap async functions
  async createUser(req: Request, res: Response, next: NextFunction): Promise<void> {
    try {
      const user = await this.userService.createUser(req.body);
      res.status(201).json(ResponseFormatter.success(user));
    } catch (error) {
      next(error); // Pass to error handler
    }
  }

  // Or use catchAsync wrapper
  getUserById = ErrorHandler.catchAsync(
    async (req: Request, res: Response): Promise<void> => {
      const user = await this.userService.getUserById(req.params.id);
      res.json(ResponseFormatter.success(user));
    }
  );
}

Rate Limiting

Prevent abuse and DOS attacks.

npm install express-rate-limit

// src/middleware/rate-limiter.ts
import rateLimit from 'express-rate-limit';
import { ResponseFormatter } from '../utils/response-formatter';

export class RateLimiter {
  // General API rate limit
  static general = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // 100 requests per window
    message: 'Too many requests, please try again later',
    standardHeaders: true,
    legacyHeaders: false,
    handler: (req, res) => {
      res.status(429).json(
        ResponseFormatter.error('Rate limit exceeded. Try again later.')
      );
    },
  });

  // Strict limit for auth endpoints
  static auth = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // 5 login attempts per window
    skipSuccessfulRequests: true, // Only count failed attempts
    message: 'Too many login attempts',
    handler: (req, res) => {
      res.status(429).json(
        ResponseFormatter.error('Too many login attempts. Account temporarily locked.')
      );
    },
  });

  // Lenient limit for public endpoints
  static public = rateLimit({
    windowMs: 1 * 60 * 1000, // 1 minute
    max: 60, // 60 requests per minute
  });
}

// Apply to routes
// src/routes/auth-routes.ts
router.post('/login', RateLimiter.auth, authController.login);
router.post('/register', RateLimiter.auth, authController.register);

// src/app.ts
this.app.use('/api', RateLimiter.general);

Request Sanitization

Prevent XSS and injection attacks.

npm install express-mongo-sanitize xss-clean hpp

// src/middleware/sanitization.ts
import mongoSanitize from 'express-mongo-sanitize';
import xss from 'xss-clean';
import hpp from 'hpp';

export class Sanitization {
  static setup(app: Application): void {
    // Prevent NoSQL injection
    app.use(mongoSanitize());

    // Prevent XSS attacks
    app.use(xss());

    // Prevent HTTP Parameter Pollution
    app.use(hpp({
      whitelist: ['sort', 'fields', 'page', 'limit'] // Allow these params to appear multiple times
    }));
  }
}

Response Formatting

Consistent error responses across the API.

// src/utils/response-formatter.ts
export interface ErrorDetail {
  field?: string;
  message: string;
  code?: string;
}

export class ResponseFormatter {
  static success<T>(
    data: T,
    message?: string,
    meta?: Record<string, any>
  ) {
    return {
      success: true,
      data,
      ...(message && { message }),
      ...(meta && { meta }),
    };
  }

  static error(
    error: string,
    errors?: ErrorDetail[] | string[]
  ) {
    return {
      success: false,
      error,
      ...(errors && { errors }),
      timestamp: new Date().toISOString(),
    };
  }

  static validationError(errors: ErrorDetail[]) {
    return {
      success: false,
      error: 'Validation failed',
      errors,
      timestamp: new Date().toISOString(),
    };
  }
}

Production Error Logging

// src/utils/logger.ts
import winston from 'winston';

export const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    // Write all logs to console
    new winston.transports.Console({
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      ),
    }),
    // Write error logs to file
    new winston.transports.File({
      filename: 'logs/error.log',
      level: 'error',
    }),
    // Write all logs to combined file
    new winston.transports.File({
      filename: 'logs/combined.log',
    }),
  ],
});

// Enhanced error handler with logging
export class ErrorHandler {
  static handle(err: Error, req: Request, res: Response, next: NextFunction): void {
    // Log to Winston
    logger.error('API Error', {
      error: err.message,
      stack: err.stack,
      path: req.path,
      method: req.method,
      body: req.body,
      user: req.user?.userId,
      ip: req.ip,
    });

    // ... rest of error handling
  }
}

Key Takeaways

1. Always validate input using schemas (Zod, Joi, etc.)

2. Use custom error classes for different error types

3. Global error handler catches all errors consistently

4. Rate limiting prevents abuse

5. Sanitize input to prevent XSS and injection attacks

6. Log errors with context for debugging

7. Hide error details in production

8. 422 for validation errors, 400 for bad requests

9. Async error handling with try/catch or catchAsync wrapper

10. Consistent error responses using ResponseFormatter

Next in series: API Documentation and Versioning—making your APIs discoverable and maintainable.

---

Good error handling turns crashes into graceful failures. Invest time upfront to save hours of debugging later.