O NestJS tem uma camada de exceções integrada que automaticamente detecta erros não tratados e os transforma em respostas HTTP apropriadas. Você sinaliza erros lançando exceções (frequentemente classes de exceção HTTP integradas), e o Nest as formata em respostas JSON estruturadas com o código de status correto.
{ , , } ;
()
() {
user = ..(id);
(!user) {
();
}
user;
}
O NestJS fornece classes de exceção mapeadas para códigos de status HTTP, e lançar uma produz uma resposta correta e estruturada automaticamente:
{ "statusCode": 404, "message": "User not found", "error": "Not Found" }
BadRequestException → 400
UnauthorizedException → 401
ForbiddenException → 403
NotFoundException → 404
ConflictException → 409
UnprocessableEntityException → 422
InternalServerErrorException → 500
Existe uma classe para cada erro HTTP comum — use a apropriada para comunicar o status correto.
// custom status + body via the base HttpException
throw new HttpException(
{ status: HttpStatus.FORBIDDEN, error: "custom message" },
HttpStatus.FORBIDDEN,
);
export class UserNotFoundException extends NotFoundException {
constructor(id: string) {
super(`User with id ${id} not found`); // domain-specific, reusable
}
}
throw new UserNotFoundException(id);
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).
// 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
Para formatação de erro consistente, logging, ou tratamento de erros não-HTTP, você usa filtros de exceção (um recurso relacionado e mais avançado).
O tratamento adequado de exceções é essencial para construir APIs confiáveis, e a camada de exceções integrada do NestJS torna isso limpo e consistente.
Entender como lançar exceções HTTP (NotFoundException, BadRequestException, etc.) é conhecimento do dia a dia — é o caminho idiomático para sinalizar erros com os códigos de status corretos e respostas JSON estruturadas e amigáveis ao cliente, sem construir manualmente respostas de erro em cada handler.
O framework automaticamente detecta essas exceções e as formata, e converte com segurança erros inesperados em 500s genéricos sem vazar detalhes internos (importante para segurança).
Conhecer as classes de exceção comuns, como lançar mensagens/exceções personalizadas, e que filtros de exceção existem para customização global (formatação consistente, logging) é fundamental para construir APIs NestJS robustas e profissionais.
O tratamento de erro limpo e consistente é uma marca de código back-end de qualidade, tornando este um aspecto central e frequentemente utilizado do framework.