4.4. Exception Handling

4.4.1. Global Exception Handling

Use @RestControllerAdvice to handle exceptions consistently across the entire application.

@RestControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(BusinessException.class)
  public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException e) {
    ErrorCode errorCode = e.getErrorCode();
    return ResponseEntity
        .status(errorCode.getHttpStatus())
        .body(ErrorResponse.of(errorCode));
  }

  @ExceptionHandler(MethodArgumentNotValidException.class)
  public ResponseEntity<ErrorResponse> handleValidationException(
      MethodArgumentNotValidException e) {
    return ResponseEntity
        .status(HttpStatus.BAD_REQUEST)
        .body(ErrorResponse.of(ErrorCode.INVALID_INPUT, e.getBindingResult()));
  }
}

4.4.2. Error Code Definition

Error codes must be centrally managed as an Enum.

@Getter
@RequiredArgsConstructor
public enum ErrorCode {

  // Common
  INVALID_INPUT(HttpStatus.BAD_REQUEST, "C001", "Invalid input value."),
  INTERNAL_SERVER_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "C002", "An internal server error has occurred."),
  RESOURCE_NOT_FOUND(HttpStatus.NOT_FOUND, "C003", "The requested resource was not found."),

  // User
  USER_NOT_FOUND(HttpStatus.NOT_FOUND, "U001", "User not found."),
  DUPLICATE_EMAIL(HttpStatus.CONFLICT, "U002", "Email is already in use.");

  private final HttpStatus httpStatus;
  private final String code;
  private final String message;
}

4.4.3. Standard Error Response Format

{
  "code": "U001",
  "message": "User not found.",
  "timestamp": "2026-02-28T10:30:00"
}