What are exception filters?

Question

Accepted Answer

**Exception filters** give you full control over how errors are **caught and transformed into responses**. They sit at the end of the request lifecycle, catching exceptions thrown anywhere in the request and letting you customize the error response format, status, and logging.

## A basic exception filter

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // catch HttpExceptions specifically
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

The `@Catch()` decorator specifies which exception types this filter handles, and the `catch()` method receives the exception plus the context — letting you craft any response you want.

## Catching ALL exceptions (including non-HTTP)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

A filter with `@Catch()` (no argument) handles every exception — the place to log unexpected errors and ensure even non-HTTP errors return a clean, safe response (without leaking stack traces to clients).

## Applying filters

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

Filters are usually applied **globally** to enforce a consistent error format across the whole API.

## Why use exception filters?

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## Filters vs throwing exceptions

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## Why it matters

Exception filters are an important NestJS feature for building robust, professional APIs with **consistent, controlled error handling**.

While NestJS's built-in exception layer already turns thrown exceptions into HTTP responses, exception filters give you full control to customize that behavior — which matters for several real concerns: enforcing a **consistent error-response shape** across every endpoint (so clients always get errors in the same format), **centralizing error logging** (capturing every error in one place rather than scattered try/catch), safely **handling unexpected non-HTTP errors** (converting them to clean 500s instead of crashing or leaking details), and **security** (hiding internal stack traces and sensitive details from clients while logging them internally).

A global "catch-all" filter combined with throwing specific HTTP exceptions in your code is the standard pattern for production-grade error handling.

Understanding when and how to use filters (versus simply throwing exceptions), and applying them globally for consistency, is a hallmark of well-built NestJS applications and reflects mature back-end practice around the often-overlooked but critical concern of error handling.