RFC 7807 Problem Details: Structured Error Responses

API errors return inconsistent formats — sometimes a string, sometimes {error: '...'}, sometimes {message: '...', code: N}. Clients need to write different parsers for each error shape.

Implement RFC 7807 Problem Details format for consistent, machine-readable errors.

interface ProblemDetails {
  type: string;       // URI identifying the problem type
  title: string;      // Short human-readable summary
  status: number;     // HTTP status code
  detail?: string;    // Specific explanation for this occurrence
  instance?: string;  // URI of the specific occurrence
  [key: string]: unknown; // Extension members
}

// Express middleware
function problemDetails(
  err: AppError,
  req: Request,
  res: Response,
  next: NextFunction
) {
  res.status(err.status).json({
    type: `https://api.example.com/errors/${err.code}`,
    title: err.title,
    status: err.status,
    detail: err.message,
    instance: req.path,
  } satisfies ProblemDetails);
}

// Content-Type must be application/problem+json
res.setHeader('Content-Type', 'application/problem+json');

RFC 7807 provides a standard error format for HTTP APIs. Clients can identify problem types by URI, display appropriate messages, and handle specific error codes programmatically.