Consistent API Responses — Why They Matter and How to Implement Them in NestJS
Every endpoint returning the same envelope, success or failure — the response shape worth settling on, and the global interceptor and exception filter that enforce it in NestJS.
As a frontend engineer, one of my biggest pain points over the years has been dealing with inconsistent API responses.
Sometimes a successful response looks like:
{
"data": [...],
"meta": {...}
}Other times it’s:
{
"result": [...],
"pagination": {...}
}And on errors? Even worse — sometimes it’s { "error": "Something went wrong" }, other times { "message": "Invalid request" }.
Inconsistency like this isn’t just annoying — it slows down development, increases bugs, and makes error handling harder.
This post is about why API response consistency matters, and how you can enforce it in NestJS using a global interceptor and exception filter.
Why Consistency Matters
Whether you’re building an internal API for your team or a public API for thousands of developers, a consistent response structure means:
- Predictable parsing – Frontend doesn’t need to guess the structure.
- Simplified error handling – One handler for all endpoints.
- Easier documentation – You can define the schema once and reuse it everywhere.
- Better DX (Developer Experience) – Less mental load, faster iteration.
My Standard API Response Structure
Here’s the format I like to use:
{
"method": "GET",
"path": "/users",
"timestamp": "2025-08-15T10:00:00.000Z",
"statusCode": 200,
"success": true,
"data": [],
"meta": null,
"error": null
}And for errors:
{
"method": "GET",
"path": "/users",
"timestamp": "2025-08-15T10:00:00.000Z",
"statusCode": 400,
"success": false,
"data": null,
"meta": null,
"error": {
"type": "Bad Request",
"message": "Validation failed",
"errors": {
"email": ["Email is required"]
}
}
}The API Response Flow
Here’s the basic lifecycle of an API request with consistent formatting:
- Request Received — API gets the HTTP request from client.
- Business Logic Execution — Controller/service handles the main process.
- Response Interceptor — Wraps all successful responses in the same format.
- Exception Filter — Catches all errors and formats them consistently.
- Final Response Sent — Frontend always receives predictable JSON.
Implementation in NestJS
We can enforce this consistency globally using two things:
- A ResponseInterceptor for success responses
- An HttpExceptionFilter for errors
Global ResponseInterceptor
import {
CallHandler,
ExecutionContext,
HttpException,
Injectable,
NestInterceptor,
} from "@nestjs/common";
import { catchError, map, Observable, throwError } from "rxjs";
import { Request, Response } from "express";
@Injectable()
export class ResponseInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
const request = context.switchToHttp().getRequest<Request>();
const response = context.switchToHttp().getResponse<Response>();
return next.handle().pipe(
map((data) => this.handleSuccess(request, response, data)),
catchError((err) => {
const statusCode = err instanceof HttpException ? err.getStatus() : 500;
return throwError(() => new HttpException(err, statusCode));
}),
);
}
private handleSuccess(request: Request, response: Response, data: any) {
const responseData = {
method: request.method,
path: request.url,
timestamp: new Date().toISOString(),
statusCode: response.statusCode,
success: true,
data: data,
meta: null,
error: null,
};
if (data?.data && data?.meta) {
responseData.data = data.data;
responseData.meta = data.meta;
}
return responseData;
}
}Global HttpExceptionFilter
import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from "@nestjs/common";
import { Request, Response } from "express";
import { STATUS_CODES } from "http";
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const request = ctx.getRequest<Request>();
const response = ctx.getResponse<Response>();
const status = exception.getStatus();
const exceptionResponse = exception.getResponse() as any;
const error = {
type:
STATUS_CODES?.[status] || exceptionResponse.response?.error || exception.name || "Error",
message:
status === 500
? "Internal Server Error"
: exceptionResponse?.response?.message || exception.message,
errors: exceptionResponse?.response?.validation || null,
};
const responseData = {
method: request.method,
path: request.url,
timestamp: new Date().toISOString(),
statusCode: status,
success: false,
data: null,
meta: null,
error,
};
response.status(status).json(responseData);
}
}Applying Globally in main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { ResponseInterceptor } from "./interceptors/response.interceptor";
import { HttpExceptionFilter } from "./filters/http-exception.filter";
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new ResponseInterceptor());
app.useGlobalFilters(new HttpExceptionFilter());
await app.listen(3000);
}
bootstrap();The Result
With this setup:
- Every success response will have the same structure.
- Every error will follow the same format.
- Your frontend engineers will love you (or at least stop complaining 😆).
Bonus: You can easily add meta for pagination or errors for validation without changing the overall shape.
Key takeaway: Consistency is more important than the exact structure. Once you decide the shape, enforce it across all endpoints.
