How do you handle exceptions in NestJS?

Question

Accepted Answer

NestJS has a **built-in exception layer** that automatically catches unhandled errors and turns them into proper HTTP responses. You signal errors by **throwing exceptions** (often built-in HTTP exception classes), and Nest formats them into structured JSON responses with the right status code.

## Throwing built-in HTTP exceptions

```ts
import { NotFoundException, BadRequestException, UnauthorizedException } from "@nestjs/common";

@Get(":id")
findOne(@Param("id") id: string) {
  const user = this.usersService.findOne(id);
  if (!user) {
    throw new NotFoundException("User not found");   // → 404 with a JSON error body
  }
  return user;
}
```

NestJS provides exception classes mapping to HTTP status codes, and throwing one produces a correct, structured response automatically:

```json
{ "statusCode": 404, "message": "User not found", "error": "Not Found" }
```

## Common built-in HTTP exceptions

```text
BadRequestException        → 400
UnauthorizedException      → 401
ForbiddenException         → 403
NotFoundException          → 404
ConflictException          → 409
UnprocessableEntityException → 422
InternalServerErrorException → 500
```

There's a class for each common HTTP error — use the appropriate one to communicate the right status.

## Custom messages and the generic HttpException

```ts
// custom status + body via the base HttpException
throw new HttpException(
  { status: HttpStatus.FORBIDDEN, error: "custom message" },
  HttpStatus.FORBIDDEN,
);
```

## Custom exception classes

```ts
export class UserNotFoundException extends NotFoundException {
  constructor(id: string) {
    super(`User with id ${id} not found`);   // domain-specific, reusable
  }
}
throw new UserNotFoundException(id);
```

## Unhandled errors become 500s

```text
If code throws a non-HttpException error (e.g. a plain Error or an unexpected
exception), NestJS's default exception filter catches it and returns a generic
500 Internal Server Error (without leaking internal details to the client).
```

## Exception filters for global customization

```ts
// a custom exception filter customizes how errors are formatted/logged globally
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // log, format the response, etc.
  }
}
app.useGlobalFilters(new AllExceptionsFilter());   // apply app-wide
```

For consistent error formatting, logging, or handling non-HTTP errors, you use **exception filters** (a related, more advanced feature).

## Why it matters

Proper exception handling is essential for building reliable APIs, and NestJS's built-in exception layer makes it clean and consistent.

Understanding how to **throw HTTP exceptions** (`NotFoundException`, `BadRequestException`, etc.) is everyday knowledge — it's the idiomatic way to signal errors with the correct status codes and structured, client-friendly JSON responses, without manually constructing error responses in every handler.

The framework automatically catches these and formats them, and it safely converts unexpected errors into generic 500s without leaking internal details (important for security).

Knowing the common exception classes, how to throw custom messages/exceptions, and that **exception filters** exist for global customization (consistent formatting, logging) is fundamental for building robust, professional NestJS APIs.

Clean, consistent error handling is a hallmark of quality back-end code, making this a core, frequently-used aspect of the framework.