interface ApiError {
  error: {
    code: string;       // Machine-readable: "VALIDATION_ERROR"
    message: string;    // Human-readable: "The email field is required"
    details?: Array<{   // Field-level errors for forms
      field: string;
      message: string;
    }>;
    requestId?: string; // For support/debugging
  };
}

class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
    public details?: Array<{ field: string; message: string }>
  ) {
    super(message);
  }
}
 
// Usage
throw new AppError(404, "NOT_FOUND", "User not found");
throw new AppError(422, "VALIDATION_ERROR", "Invalid input", [
  { field: "email", message: "must be a valid email address" },
]);

app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  const requestId = req.headers["x-request-id"] || crypto.randomUUID();
 
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        details: err.details,
        requestId,
      },
    });
  }
 
  // Unexpected errors — log full details, return generic message
  console.error({ requestId, error: err.message, stack: err.stack });
  return res.status(500).json({
    error: {
      code: "INTERNAL_ERROR",
      message: "An unexpected error occurred",
      requestId,
    },
  });
});

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfter": 30
  }
}