API Error Handling: RFC 7807 Problem Details & Best Practices

Consistent, informative error responses are a mark of a well-designed API. This guide covers the HTTP status code vocabulary, the RFC 7807 Problem Details standard, validation error patterns, and Express middleware for centralizing error handling.

HTTP Status Code Quick Reference

RFC 7807 Problem Details Format

Use Content-Type: application/problem+json and structure errors as standardized Problem Details objects. Extend with custom fields as needed:

// HTTP 422 Unprocessable Entity
// Content-Type: application/problem+json

{
  "type": "https://devplaybook.cc/problems/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body contains invalid fields.",
  "instance": "/requests/f7ab2c10-a1b2-4c3d",
  "errors": [
    {
      "pointer": "/data/attributes/email",
      "detail": "Must be a valid email address",
      "code": "invalid_email"
    },
    {
      "pointer": "/data/attributes/age",
      "detail": "Must be a positive integer",
      "code": "invalid_range"
    }
  ]
}

Express Central Error Handler

Centralize all error formatting in a single Express error middleware registered last. Custom error classes carry status codes and structured detail:

// errors/AppError.ts
export class AppError extends Error {
  constructor(
    public readonly status: number,
    public readonly type: string,
    message: string,
    public readonly errors?: object[],
  ) { super(message); }
}

export class ValidationError extends AppError {
  constructor(errors: { pointer: string; detail: string; code: string }[]) {
    super(422, 'https://devplaybook.cc/problems/validation-error',
      'Validation Failed', errors);
  }
}

// middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

export function errorHandler(err: any, req: Request, res: Response, _next: NextFunction) {
  // Never expose stack traces in production
  if (process.env.NODE_ENV !== 'production') console.error(err);

  const status = err.status ?? 500;
  const body: Record<string, unknown> = {
    type: err.type ?? 'https://devplaybook.cc/problems/internal-error',
    title: err.message ?? 'An unexpected error occurred',
    status,
    instance: req.path,
  };

  if (err.errors) body.errors = err.errors;

  // Log internal errors with correlation ID
  if (status >= 500) {
    const correlationId = req.headers['x-correlation-id'] ?? crypto.randomUUID();
    console.error({ correlationId, error: err.message, stack: err.stack });
    body.correlationId = correlationId;
    body.title = 'An unexpected error occurred';  // sanitize message
  }

  res.status(status).contentType('application/problem+json').json(body);
}