¿Qué son los filtros de excepciones?

Question

Accepted Answer

**Los filtros de excepciones** te dan control total sobre cómo los errores son **capturados y transformados en respuestas**. Se sitúan al final del ciclo de vida de la solicitud, capturando excepciones lanzadas en cualquier parte de la solicitud y permitiéndote personalizar el formato, estado y registro de la respuesta de error.

## Un filtro de excepciones básico

```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,
    });
  }
}
```

El decorador `@Catch()` especifica qué tipos de excepciones maneja este filtro, y el método `catch()` recibe la excepción más el contexto — permitiéndote crear cualquier respuesta que desees.

## Capturar TODAS las excepciones (incluyendo las no-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: "..." });
  }
}
```

Un filtro con `@Catch()` (sin argumento) maneja cada excepción — el lugar para registrar errores inesperados y asegurar que incluso los errores no-HTTP devuelvan una respuesta limpia y segura (sin filtrar stack traces a los clientes).

## Aplicar filtros

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

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

Los filtros generalmente se aplican **globalmente** para garantizar un formato de error consistente en toda la API.

## Por qué usar filtros de excepciones?

```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
```

## Filtros vs lanzar excepciones

```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.
```

## Por qué es importante

Los filtros de excepciones son una característica importante de NestJS para construir APIs robustas y profesionales con **manejo de errores consistente y controlado**.

Aunque la capa de excepciones integrada de NestJS ya convierte las excepciones lanzadas en respuestas HTTP, los filtros de excepciones te dan control total para personalizar ese comportamiento — lo que importa para varios problemas reales: garantizar una **forma de respuesta de error consistente** en cada endpoint (para que los clientes siempre reciban errores en el mismo formato), **centralizar el registro de errores** (capturando cada error en un solo lugar en lugar de disperso en try/catch), manejar de forma segura **errores inesperados no-HTTP** (convirtiéndolos en 500 limpios en lugar de fallos o filtraciones de detalles), y **seguridad** (ocultando stack traces internos y detalles sensibles de los clientes mientras se registran internamente).

Un filtro "catch-all" global combinado con lanzar excepciones HTTP específicas en tu código es el patrón estándar para manejo de errores de grado de producción.

Entender cuándo y cómo usar filtros (versus simplemente lanzar excepciones), y aplicarlos globalmente para consistencia, es una característica distintiva de aplicaciones NestJS bien construidas y refleja práctica back-end madura alrededor de la preocupación crítica pero a menudo pasada por alto del manejo de errores.