NestJS Error Handling Standards

Priority: P1 (OPERATIONAL)

Global error handling and exception management patterns.

• Requirement: Centralize error formatting.

• Platform Agnostic: Do not import

  Request

  /

  Response

  from Express/Fastify types directly.
  • Use:

    HttpAdapterHost

    to access the underlying platform response methods.

  • const { httpAdapter } = this.httpAdapterHost;

• Structure:

  • Implement strictly typed error responses.
  • Refer to API Standards for

    ApiErrorResponse

    .

  {
    "statusCode": 400,
    "message": "Validation failed",
    "error": "Bad Request",
    "timestamp": "ISO...",
    "path": "/users"
  }
  

Error Flow

1. Service: Throws specific or generic errors (e.g.,

   EntityNotFoundError

   ).
2. Interceptor: Maps low-level errors to HTTP Exceptions (e.g.,

   catchError(err => throw new NotFoundException())

   ).
   • Why: Keeps Exception Filters focused on formatting, not business logic interpretation.
3. Global Filter: Formats the final JSON response.

Built-in Exceptions

• Use: Throw

  NotFoundException

  ,

  ForbiddenException

  ,

  BadRequestException

  .
• Custom: Extend

  HttpException

  only for domain-specific failures that need specific status codes.

Logging

• Context: Always pass

  MyClass.name

  to the

  Logger

  constructor.
• Levels:

  • error

    : 500s (Stack trace required).

  • warn

    : 400s (Client errors).

Security (Information Leakage)

• Production: NEVER expose stack traces in HTTP responses (

  process.env.NODE_ENV === 'production'

  ).
• Sanitization: Ensure

  ApiException

  payloads do not leak internal file paths or raw variable dumps.

Anti-Patterns

• No stack traces in production: Gate stack exposure behind

  NODE_ENV === 'production'

  check.
• No Express types in filters: Use

  HttpAdapterHost

  for platform-agnostic error handling.
• No HttpException in services: Throw domain errors in services; let Interceptors map to HTTP exceptions.