📤 Response Formatting and Status Codes

Why Response Design Matters

A response carries two channels of information: the status code (what happened, at a glance) and the body (the details). When those two are consistent across every endpoint, the developers consuming your API — including future you — can write generic handling once instead of special-casing each route.

💡 Think of it this way: An API is only as good as its response design. The response is your API's voice — make it speak clearly, and in the same accent everywhere.

Consistent responses pay off in developer experience, graceful error handling on the client, faster debugging (the status code shows up in every log and network tab), and self-documentation — a well-shaped response teaches the client how to read it.

Status Code Categories

Every HTTP status code falls into one of five ranges. Knowing the range tells you the shape of the outcome before you read the exact number.

The right code depends on the operation. This table maps common REST actions to their typical outcomes:

Setting Codes in Express

Express makes status codes easy: res.status(code) sets the code and returns the response object, so you can chain the body method.

app.get('/api/users/:id', (req, res) => {
  const user = findUser(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.status(200).json(user); // chainable: status → json
});

There's also res.sendStatus(code), which sets the code and sends the standard reason phrase as the body — handy for terse responses where no JSON is needed:

res.sendStatus(204); // → 204, body: "No Content"
res.sendStatus(403); // → 403, body: "Forbidden"

A Consistent Response Envelope

An envelope is the outer shape every response shares. Whether the request succeeded or failed, the client finds the same top-level keys and knows exactly where to look. Here's a common, minimal pattern:

// Success — a single resource
{ "success": true, "data": { "id": 7, "title": "Ship v2" } }

// Success — a collection with metadata
{
  "success": true,
  "data": [ /* items */ ],
  "meta": { "total": 57, "page": 2, "limit": 10, "pages": 6 }
}

// Error — always the same shape
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid order data",
    "details": { "quantity": "must be greater than 0" }
  }
}

💡 Analogy: A response envelope is like a company report template. No matter which department files it, the summary, the data, and the conclusions are always in the same place — so any reader knows how to skim it instantly.

The JSend Convention

Rather than invent your own envelope, you can adopt a published one. JSend is the simplest: it defines three outcomes — success, fail (the client's fault, e.g. validation), and error (the server's fault).

// success — the request worked
{ "status": "success", "data": { "id": 1, "name": "John Doe" } }

// fail — client-side problem (validation, bad input)
{ "status": "fail", "data": { "email": "Email is already in use" } }

// error — server-side problem
{ "status": "error", "message": "Unable to reach the database" }

Implementing JSend as a tiny helper keeps every route terse and uniform:

// utils/jsend.js
const jsend = {
  success: (res, data, statusCode = 200) =>
    res.status(statusCode).json({ status: 'success', data: data ?? null }),

  fail: (res, data, statusCode = 400) =>
    res.status(statusCode).json({ status: 'fail', data }),

  error: (res, message, statusCode = 500, code = null) => {
    const body = { status: 'error', message };
    if (code) body.code = code;
    return res.status(statusCode).json(body);
  },
};

module.exports = jsend;

const jsend = require('./utils/jsend');

app.get('/api/users/:id', (req, res) => {
  const user = findUser(req.params.id);
  if (!user) return jsend.fail(res, { id: 'User not found' }, 404);
  return jsend.success(res, user);
});

Response Helpers & Middleware

To keep formatting DRY, wrap it in reusable code. Two common shapes: a helper object, or a class attached to res via middleware.

A response helper class

// utils/api-response.js
class ApiResponse {
  constructor(res) {
    this.res = res;
  }

  success(data = null, meta = null, statusCode = 200) {
    const body = { success: true, data };
    if (meta) body.meta = meta;
    return this.res.status(statusCode).json(body);
  }

  created(data = null) {
    return this.success(data, null, 201);
  }

  noContent() {
    return this.res.status(204).send();
  }

  error(message, code = 'ERROR', statusCode = 500, details = null) {
    return this.res.status(statusCode).json({
      success: false,
      error: { code, message, details },
    });
  }

  notFound(resource = 'Resource') {
    return this.error(`${resource} not found`, 'NOT_FOUND', 404);
  }

  badRequest(message, details = null) {
    return this.error(message, 'BAD_REQUEST', 400, details);
  }
}

module.exports = ApiResponse;

Attach it to every request with a one-line middleware, and your controllers become wonderfully readable:

const ApiResponse = require('./utils/api-response');

app.use((req, res, next) => {
  res.api = new ApiResponse(res);
  next();
});

app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) return res.api.notFound('User');
  return res.api.success(user);
});

Formatting middleware (override res.json)

An alternative is to intercept res.json once so every response is wrapped automatically, without touching each handler:

// middleware/response-formatter.js
module.exports = (req, res, next) => {
  const originalJson = res.json.bind(res);

  res.json = (body) => {
    // Don't double-wrap already-formatted responses
    if (body && (body.success !== undefined || body.status)) {
      return originalJson(body);
    }
    const success = res.statusCode >= 200 && res.statusCode < 300;
    return originalJson(
      success
        ? { success: true, data: body }
        : { success: false, error: body }
    );
  };

  next();
};

Pagination & Headers

Collections should never dump every row. Paginate, and tell the client how to navigate via meta:

app.get('/api/products', async (req, res) => {
  const page = Number(req.query.page) || 1;
  const limit = Number(req.query.limit) || 10;
  const skip = (page - 1) * limit;

  const [items, total] = await Promise.all([
    Product.find().skip(skip).limit(limit),
    Product.countDocuments(),
  ]);

  const pages = Math.ceil(total / limit);
  res.status(200).json({
    success: true,
    data: items,
    meta: {
      pagination: {
        total, page, limit, pages,
        hasNext: page < pages,
        hasPrev: page > 1,
      },
    },
  });
});

For very large or fast-changing datasets, cursor-based pagination (pass an opaque cursor instead of a page number) is more stable and efficient than offset pagination, because inserts don't shift the page boundaries.

Useful response headers

Headers carry metadata that doesn't belong in the body. A few worth knowing:

app.post('/api/products', async (req, res) => {
  const product = await Product.create(req.body);
  res
    .status(201)
    .location(`/api/products/${product.id}`) // where to find it
    .json({ success: true, data: product });
});

Hands-on Exercise

// utils/api-response.js
class ApiResponse {
  constructor(res) { this.res = res; }

  success(data = null, meta = null, statusCode = 200) {
    const body = { success: true, data };
    if (meta) body.meta = meta;
    return this.res.status(statusCode).json(body);
  }

  created(data) { return this.success(data, null, 201); }

  notFound(resource = 'Resource') {
    return this.res.status(404).json({
      success: false,
      error: { code: 'NOT_FOUND', message: `${resource} not found` },
    });
  }

  paginated(items, page, limit, total) {
    const pages = Math.ceil(total / limit);
    return this.success(items, {
      pagination: { total, page, limit, pages,
        hasNext: page < pages, hasPrev: page > 1 },
    });
  }
}
module.exports = ApiResponse;

// app.js
const express = require('express');
const ApiResponse = require('./utils/api-response');

const app = express();
app.use(express.json());
app.use((req, res, next) => { res.api = new ApiResponse(res); next(); });

const notes = [
  { id: '1', text: 'First note' },
  { id: '2', text: 'Second note' },
];

app.get('/api/notes', (req, res) => {
  const page = Number(req.query.page) || 1;
  const limit = Number(req.query.limit) || 10;
  const start = (page - 1) * limit;
  const pageItems = notes.slice(start, start + limit);
  res.api.paginated(pageItems, page, limit, notes.length);
});

app.get('/api/notes/:id', (req, res) => {
  const note = notes.find(n => n.id === req.params.id);
  if (!note) return res.api.notFound('Note');
  res.api.success(note);
});

app.listen(3000, () => console.log('http://localhost:3000'));

Summary & Quiz

📚 Further Reading

• MDN — HTTP response status codes
• JSend specification
• Express — Response (res) API

🚀 What's Next?

You can now shape every reply — including error replies. Next we'll centralize how those errors are produced with error handling middleware, so a thrown error anywhere becomes a clean, consistent response automatically.