이메일 중복 확인 API의 Validation 오류가 500으로 반환된 문제

1. 문제 상황

이메일 중복 확인 API에 잘못된 이메일 형식을 전달했을 때, 예상했던 400 Bad Request 대신 500 Internal Server Error가 반환됐다.

사용자의 입력값이 잘못된 요청인데 서버 내부 오류로 처리되고 있었다.

해당 파라미터에는 다음과 같이 검증 조건을 적용한 상태였다.

@RequestParam
@NotBlank
@Email
String email

2. 원인

기존 GlobalExceptionHandler에서는 요청 Body의 DTO 검증 실패에 사용하는 MethodArgumentNotValidException을 처리하고 있었다.

하지만 이번 요청은 @RequestParam에 직접 검증 조건을 적용했고, 실제로 발생한 예외는 HandlerMethodValidationException이었다.

당시 두 요청 방식에서 발생한 예외는 다음과 같았다.

@RequestBody DTO 검증 실패
→ MethodArgumentNotValidException

이메일 @RequestParam 검증 실패
→ HandlerMethodValidationException

HandlerMethodValidationException을 처리하는 Handler가 없었기 때문에, 예외가 공통 RuntimeException Handler로 전달되어 500 응답으로 처리됐다.

3. 해결

GlobalExceptionHandler에 HandlerMethodValidationException을 처리하는 메서드를 추가했다.

@ExceptionHandler(HandlerMethodValidationException.class)
public ResponseEntity<ExceptionResponseDto> handleMethodValidationException(
        HandlerMethodValidationException e
) {
    log.warn("Method Validation 오류 발생: {}", e.getMessage());

    String message = "잘못된 요청입니다.";
    String field = null;

    if (!e.getParameterValidationResults().isEmpty()) {
        var result = e.getParameterValidationResults().getFirst();

        if (!result.getResolvableErrors().isEmpty()) {
            message = result.getResolvableErrors()
                    .getFirst()
                    .getDefaultMessage();
        }

        field = result.getMethodParameter()
                .getParameterName();
    }

    return ResponseEntity
            .badRequest()
            .body(ExceptionResponseDto.ofValidation(
                    HttpStatus.BAD_REQUEST.value(),
                    message,
                    field
            ));
}

검증 결과에서 첫 번째 파라미터의 오류 메시지와 파라미터 이름을 가져와 기존 ExceptionResponseDto 형식으로 반환하도록 했다. 검증 결과가 없을 때 사용할 기본 메시지도 지정했다.

이렇게 처리한 요청 검증 오류는 400 Bad Request로 응답한다. 기존에는 공통 RuntimeException Handler로 넘어가던 예외를 별도로 처리하면서, 잘못된 입력이 서버 내부 오류로 반환되는 문제를 해결했다.

4. 확인 결과와 배운 점

수정 후 잘못된 이메일 형식으로 다시 요청했을 때 400 Bad Request가 반환되는 것을 확인했다.

같은 입력값 검증 실패라도 검증이 적용되는 위치와 방식에 따라 발생하는 예외가 다를 수 있었다. 검증 어노테이션을 추가하는 것뿐 아니라, 실제 예외가 의도한 응답으로 처리되는지도 확인해야 한다는 점을 배웠다.