📦 API Response Utility – Usage Guide

A lightweight utility to standardize API responses for Node.js/Express applications. This helps maintain consistent response formats for success and error handling across your backend services.

🚀 Installation

npm install api-response-utility

Importing

const {
  success,
  error,
  validationError,
  routeNotFound,
  notFound,
  unauthorized,
  forbidden,
  conflict,
  tooManyRequests,
  internalServerError
} = require('api-response-utility');

Success Response

res.status(200).json(success({ userId: 123 }, "User retrieved successfully"));

Output

{
  "success": true,
  "message": "User retrieved successfully",
  "data": {
    "userId": 123
  },
  "statusCode": 200
}

Error Responses

res.status(500).json(error("Something went wrong", 500));

Output

{
  "success": false,
  "message": "Something went wrong",
  "errors": [],
  "statusCode": 500
}

Validation Error

res.status(422).json(validationError([
  { field: "email", msg: "Invalid email address" }
]));

Output

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "msg": "Invalid email address" }
  ],
  "statusCode": 422
}

Unauthorized

res.status(401).json(unauthorized("You must be logged in"));

Output

{
  "success": false,
  "message": "You must be logged in",
  "errors": [],
  "statusCode": 401
}

Forbidden

res.status(403).json(forbidden("Access denied to this resource"));

Output

{
  "success": false,
  "message": "Access denied to this resource",
  "errors": [],
  "statusCode": 403
}

Not Found

app.use((req, res) => {
  res.status(404).json(routeNotFound(req.originalUrl));
});

Output

{
  "success": false,
  "message": "User not found",
  "errors": [],
  "statusCode": 404
}

Route Not Found (Fallback Middleware)

app.use((req, res) => {
  res.status(404).json(routeNotFound(req.originalUrl));
});

Output

{
  "success": false,
  "message": "Route \"/unknown\" not found",
  "statusCode": 404
}

Conflict

res.status(409).json(conflict("Email already exists"));

Output

{
  "success": false,
  "message": "Email already exists",
  "errors": [],
  "statusCode": 409
}

Too Many Requests

res.status(429).json(tooManyRequests());

Output

{
  "success": false,
  "message": "Too many requests",
  "errors": [],
  "statusCode": 429
}

Internal Server Error

res.status(500).json(internalServerError());

Output

{
  "success": false,
  "message": "Internal server error",
  "errors": [],
  "statusCode": 500
}

Credits

Implementation (c) 2025 Gulam Ashraf. MIT LICENSE