NestJs - HTTP 예외 처리 클래스

import { ~~~ } from '@nestjs/common';

 

NestJS에서 제공하는 기본적인 HTTP 예외 처리 클래스

예외 클래스	HTTP  상태 코드	설명
BadRequestException	400	잘못된 요청 (유효성 검사 실패, 잘못된 입력 데이터 등)
UnauthorizedException	401	인증 실패 (로그인 필요)
PaymentRequiredException	402	결제 필요 (거의 사용되지 않음)
ForbiddenException	403	접근 금지 (권한 부족)
NotFoundException	404	리소스를 찾을 수 없음
MethodNotAllowedException	405	지원되지 않는 HTTP 메서드 사용
NotAcceptableException	406	요청한 응답 형식이 지원되지 않음
ProxyAuthenticationRequiredException	407	프록시 인증 필요
RequestTimeoutException	408	요청 시간 초과
ConflictException	409	데이터 충돌 (중복 데이터, 상태 충돌 등)
GoneException	410	더 이상 사용되지 않는 리소스 요청
LengthRequiredException	411	Content-Length 헤더가 필요함
PreconditionFailedException	412	요청 조건이 충족되지 않음
PayloadTooLargeException	413	요청 본문 크기가 너무 큼
URITooLongException	414	요청 URL이 너무 김
UnsupportedMediaTypeException	415	지원되지 않는 콘텐츠 타입
RequestedRangeNotSatisfiableException	416	요청한 범위를 처리할 수 없음
ExpectationFailedException	417	Expect 헤더 요구사항이 충족되지 않음
IAmATeapotException	418	"나는 찻주전자입니다" (장난스러운 상태 코드)
MisdirectedException	421	잘못된 서버에 요청 보냄
UnprocessableEntityException	422	요청은 이해되었지만 처리할 수 없음 (데이터 검증 실패)
FailedDependencyException	424	종속된 요청이 실패함
TooManyRequestsException	429	너무 많은 요청 (Rate Limit 초과)
InternalServerErrorException	500	서버 내부 오류
NotImplementedException	501	서버에서 지원하지 않는 기능
BadGatewayException	502	게이트웨이 오류
ServiceUnavailableException	503	서버가 일시적으로 사용 불가
GatewayTimeoutException	504	게이트웨이 시간 초과

 

---

✅ 예외 사용 예시

import { BadRequestException, NotFoundException } from '@nestjs/common';

throw new BadRequestException('잘못된 요청입니다.');
throw new NotFoundException('해당 데이터를 찾을 수 없습니다.');

🛠 커스텀 예외 메시지 추가

throw new BadRequestException({
  statusCode: 400,
  message: '잘못된 요청입니다.',
  error: 'Bad Request',
});

🔥 글로벌 예외 필터 (@Catch()) 활용

import { ExceptionFilter, Catch, ArgumentsHost, BadRequestException } from '@nestjs/common';

@Catch(BadRequestException)
export class BadRequestFilter implements ExceptionFilter {
  catch(exception: BadRequestException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    response.status(400).json({
      statusCode: 400,
      message: exception.message || '잘못된 요청',
    });
  }
}

이제 모든 BadRequestException이 위 필터에 의해 처리됨

---

🚀 자주 사용하는 예외

• 잘못된 입력 데이터 → BadRequestException (400)
• 인증 실패 → UnauthorizedException (401)
• 권한 부족 → ForbiddenException (403)
• 데이터 없음 → NotFoundException (404)
• 데이터 충돌 → ConflictException (409)
• 서버 오류 → InternalServerErrorException (500)