본문으로 건너뛰기
Advertisement

7.1 기본 예외 처리 메커니즘

스프링 부트(Spring Boot)는 애플리케이션 실행 중 예외(Exception)가 발생하면, 개발자가 특별한 설정을 하지 않아도 이를 감지하고 처리하는 기본적인 에러 처리 메커니즘(BasicErrorController) 을 제공합니다.

화이트라벨 에러 페이지 (Whitelabel Error Page)​

엔드포인트에서 예외가 던져지거나 404 Not Found 같은 상태가 발생했을 때, 브라우저를 통해 접속한 사용자에게는 화이트라벨 에러 페이지라는 기본 HTML 응답을 제공합니다. 이는 톰캣(Tomcat) 스택 트레이스 화면을 가려주는 역할을 합니다.

REST API에서의 기본 응답 구조​

만약 클라이언트가 Accept: application/json 헤더를 포함하여 API 요청을 보낸 경우, 스프링 부트는 HTML 대신 아래와 같은 JSON 형태의 오류 응답을 내보냅니다.

{
  "timestamp": "2026-03-14T03:00:00.000+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "path": "/api/users"
}

이 기본 응답 객체는 장애 발생 시점과 상태, 에러 종류, 발생 경로 등을 담고 있어 초기 개발에 매우 유용합니다.

기본 처리의 한계​

하지만 서비스가 고도화될수록 스프링 기본 설정만으로는 한계에 부딪힙니다.

  1. 일관성 부족: 클라이언트(프론트엔드) 입장에서는 정상 응답의 JSON 구조와 오류 응답의 JSON 구조가 다르기 때문에 통일된 에러 핸들링을 하기 어렵습니다.
  2. 비즈니스 콘텍스트 부족: "권한 오류", "잔액 부족", "상품 재고 없음" 과 같이 비즈니스 규칙에 의해 거절된 섬세한 예외 상황을 HTTP 상태 코드(400, 500 등) 하나만으로 세분화해서 알리기가 어렵습니다.
  3. 불필요한 정보 노출: 때로는 콘솔에 찍히는 서버 내부의 스택 트레이스를 그대로 응답 객체로 노출할 위험이 있어 보안상 좋지 않습니다.

따라서 실무에서는 스프링이 제공하는 @RestControllerAdvice 기반의 전역 예외 처리(Global Exception Handling) 시스템을 구축하여, 프론트엔드와 약속한 통일된 포맷으로 에러 응답을 내려주는 방식을 사용합니다.

Advertisement
Advertisement