Standardizing API Responses with NestJS Interceptors

The Problem: Inconsistent API Response Structures

When building a growing API, different developers often return data in different formats. One endpoint might return a raw array, while another returns an object with a data key. This inconsistency forces frontend developers to write conditional logic for every single API call to handle varying response shapes.

The most efficient way to solve this in NestJS is through an Interceptor. Interceptors allow you to wrap the result of every route handler in a consistent envelope without modifying the individual controller methods.

How Response Interceptors Work

An interceptor implements the NestInterceptor interface. It uses the intercept() method to wrap the request-response cycle. Because NestJS uses RxJS under the hood for its stream handling, you use the map operator to transform the data returned by the controller before it is sent to the client.

The execution order is critical: Guards → Interceptors (pre-handler) → Pipes → Controller → Interceptors (post-handler). This means interceptors are the ideal place for response transformation because they have access to the final result of the controller logic.

Implementation: The TransformInterceptor

Below is a production-ready example of a global interceptor that wraps all successful responses in a standard { "data": T, "timestamp": string } object.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface ResponseEnvelope<T> {
  data: T;
  timestamp: string;
}

@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      map(data => ({
        data: data,
        timestamp: new Date().toISOString(),
      }))
    );
  }
}

Applying the Interceptor

You have two primary ways to apply this logic depending on the required scope:

• Controller/Method Level: Use the @UseInterceptors(TransformInterceptor) decorator. This is best for specific endpoints that require unique formatting.
• Global Level (with DI): To allow the interceptor to use other services (like a ConfigService), register it in your AppModule using the APP_INTERCEPTOR token.

// app.module.ts
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { TransformInterceptor } from './interceptors/transform.interceptor';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: TransformInterceptor,
    },
  ],
})
export class AppModule {}

Critical Limitations and Common Pitfalls

The RxJS "Hanging" Request

The most common mistake when writing interceptors is failing to return the observable chain. If you call next.handle() but do not return it, or if you break the stream without emitting a value, the HTTP request will hang indefinitely until the client times out. Always ensure the intercept method returns the result of the pipe operation.

Interceptors vs. Guards

Interceptors cannot be used for primary authentication. Because Guards execute before Interceptors, any logic requiring a verified user identity (like checking a JWT) must happen in a Guard. If you place authentication in an interceptor, you are executing expensive logic after the request has already passed through the security layer.

Business Logic Leakage

Avoid placing complex business rules inside interceptors. Interceptors are for cross-cutting concerns (logging, transforming, caching). If you find yourself writing if/else blocks based on specific database values inside an interceptor, that logic belongs in a Service class.

Verification and Testing

To verify the implementation, perform a request to any endpoint using a tool like cURL or Postman.

Expected Result:
If your controller returns return { id: 1, name: 'Test' };, the client should receive:

{
  "data": {
    "id": 1,
    "name": "Test"
  },
  "timestamp": "2026-10-13T11:57:21.000Z"
}
Diagnostic Check: If the response is still the raw object, check if you have multiple interceptors competing or if the APP_INTERCEPTOR provider is missing from the root module.
Rollback Procedure
To revert this change, remove the APP_INTERCEPTOR provider from the AppModule or remove the @UseInterceptors() decorator from the affected controllers. This will immediately return the API to its original, raw response format.