Spring Boot

Handle exceptions and perform validation in REST APIs using @ControllerAdvice, @ExceptionHandler, and @Valid

By Utility Zone · 2025-11-01T14:41:59.11049

Now I have comprehensive information to create a detailed guide on exception handling and validation in Spring Boot REST APIs. Let me generate the response.

Exception Handling and Validation in Spring Boot REST APIs

Handling exceptions and validating input data are critical aspects of building robust REST APIs with Spring Boot. Spring provides powerful annotations like @ControllerAdvice, @ExceptionHandler, and @Valid to implement centralized exception handling and automatic validation seamlessly.

Setting Up Dependencies

First, ensure you have the necessary dependency in your pom.xml. For Spring Boot 2.3+, you need to explicitly add the validation starter:¹

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

The validation starter includes Hibernate Validator, the reference implementation of Jakarta Bean Validation.²¹

Understanding the Key Annotations

@ControllerAdvice vs @RestControllerAdvice

Both annotations enable global exception handling across all controllers, but with a key difference:³⁴

@ControllerAdvice: Used for traditional Spring MVC applications that return views. Requires @ResponseBody on handler methods to return JSON responses
@RestControllerAdvice: A specialized version that combines @ControllerAdvice + @ResponseBody, designed specifically for RESTful services that return JSON/XML directly⁴⁵

@RestControllerAdvice = @ControllerAdvice + @ResponseBody

@ExceptionHandler

This annotation marks methods that handle specific exceptions. Methods annotated with @ExceptionHandler are automatically recognized by Spring as exception handlers. You can handle multiple exception types in a single method or create separate handlers for different exceptions.⁶⁷⁸

@Valid

This annotation triggers validation on annotated objects based on Jakarta Bean Validation constraints defined on the class fields. When validation fails, Spring automatically throws a MethodArgumentNotValidException.⁹¹⁰

Implementing Bean Validation

Step 1: Add Validation Constraints to Your Entity/DTO

Apply validation annotations to your model fields:²¹

import jakarta.validation.constraints.*;

public class Employee {
    
    @NotNull(message = "ID cannot be null")
    private Long id;
    
    @NotBlank(message = "First name is required")
    @Size(min = 3, max = 20, message = "First name should be between 3 and 20 characters")
    private String firstName;
    
    @NotBlank(message = "Last name is required")
    @Size(min = 3, max = 20, message = "Last name should be between 3 and 20 characters")
    private String lastName;
    
    @Email(message = "Email is invalid")
    @NotBlank(message = "Email is required")
    private String email;
    
    @Min(value = 18, message = "Age must be at least 18")
    @Max(value = 65, message = "Age must not exceed 65")
    private Integer age;
    
    @Pattern(regexp = "^[0-9]{10}quot;, message = "Phone number must be 10 digits")
    private String phoneNumber;
    
    // Getters and setters
}

Common Validation Annotations:¹¹¹²⁹

@NotNull: Field must not be null
@NotBlank: String must not be null or empty (ignores whitespace)
@NotEmpty: Collection/String must not be null or empty
@Size(min, max): String/Collection size must be within range
@Min(value) / @Max(value): Numeric value constraints
@Email: Must be a valid email address
@Pattern(regexp): Must match the specified regex
@Positive / @Negative: Numeric sign validation
@Past / @Future: Date must be in past/future

Step 2: Enable Validation in REST Controller

Use @Valid annotation with @RequestBody to trigger automatic validation:⁹²

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {
    
    @Autowired
    private EmployeeRepository employeeRepository;
    
    @PostMapping
    public ResponseEntity<Employee> createEmployee(
            @Valid @RequestBody Employee employee) {
        
        Employee savedEmployee = employeeRepository.save(employee);
        return new ResponseEntity<>(savedEmployee, HttpStatus.CREATED);
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<Employee> updateEmployee(
            @PathVariable Long id,
            @Valid @RequestBody Employee employee) {
        
        Employee existingEmployee = employeeRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Employee not found with id: " + id));
        
        existingEmployee.setFirstName(employee.getFirstName());
        existingEmployee.setLastName(employee.getLastName());
        existingEmployee.setEmail(employee.getEmail());
        
        return ResponseEntity.ok(employeeRepository.save(existingEmployee));
    }
}

Validating Path Variables and Query Parameters

For primitive types like path variables and request parameters, use @Validated at the class level:⁹

@RestController
@RequestMapping("/api/users")
@Validated  // Required for parameter validation
public class UserController {
    
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(
            @PathVariable @Min(1) Long id) {
        // Implementation
    }
    
    @GetMapping("/search")
    public ResponseEntity<List<User>> searchUsers(
            @RequestParam @NotBlank @Size(min = 3) String name) {
        // Implementation
    }
}

This triggers ConstraintViolationException instead of MethodArgumentNotValidException.⁹

Creating Custom Error Response Structure

Define a standardized error response format:⁷¹³³

public class ErrorResponse {
    
    private int statusCode;
    private Date timestamp;
    private String message;
    private String description;
    
    public ErrorResponse(int statusCode, Date timestamp, String message, String description) {
        this.statusCode = statusCode;
        this.timestamp = timestamp;
        this.message = message;
        this.description = description;
    }
    
    // Getters and setters
}

For validation errors with field-level details:⁹

public class ValidationErrorResponse {
    
    private List<Violation> violations = new ArrayList<>();
    
    // Getters and setters
}

public class Violation {
    
    private final String fieldName;
    private final String message;
    
    public Violation(String fieldName, String message) {
        this.fieldName = fieldName;
        this.message = message;
    }
    
    // Getters
}

Creating Custom Exceptions

Define custom exceptions for specific business scenarios:¹³³

public class ResourceNotFoundException extends RuntimeException {
    
    private static final long serialVersionUID = 1L;
    
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

public class BusinessValidationException extends RuntimeException {
    
    public BusinessValidationException(String message) {
        super(message);
    }
}

Implementing Global Exception Handler

Create a centralized exception handler using @RestControllerAdvice:³⁶⁷¹³

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;

import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import java.util.Date;

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    // Handle custom ResourceNotFoundException
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleResourceNotFoundException(
            ResourceNotFoundException ex, WebRequest request) {
        
        ErrorResponse message = new ErrorResponse(
            HttpStatus.NOT_FOUND.value(),
            new Date(),
            ex.getMessage(),
            request.getDescription(false)
        );
        
        return message;
    }
    
    // Handle validation errors for @Valid on @RequestBody
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ValidationErrorResponse handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex) {
        
        ValidationErrorResponse error = new ValidationErrorResponse();
        
        for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
            error.getViolations().add(
                new Violation(fieldError.getField(), fieldError.getDefaultMessage())
            );
        }
        
        return error;
    }
    
    // Handle validation errors for @Validated on path variables/parameters
    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ValidationErrorResponse handleConstraintViolation(
            ConstraintViolationException ex) {
        
        ValidationErrorResponse error = new ValidationErrorResponse();
        
        for (ConstraintViolation<?> violation : ex.getConstraintViolations()) {
            error.getViolations().add(
                new Violation(
                    violation.getPropertyPath().toString(),
                    violation.getMessage()
                )
            );
        }
        
        return error;
    }
    
    // Handle business validation exceptions
    @ExceptionHandler(BusinessValidationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleBusinessValidationException(
            BusinessValidationException ex, WebRequest request) {
        
        return new ErrorResponse(
            HttpStatus.BAD_REQUEST.value(),
            new Date(),
            ex.getMessage(),
            request.getDescription(false)
        );
    }
    
    // Handle all other exceptions
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGlobalException(
            Exception ex, WebRequest request) {
        
        ErrorResponse message = new ErrorResponse(
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            new Date(),
            ex.getMessage(),
            request.getDescription(false)
        );
        
        return message;
    }
}

Using ResponseEntityExceptionHandler

For more control, extend ResponseEntityExceptionHandler:¹⁴⁷¹

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@RestControllerAdvice
public class CustomExceptionHandler extends ResponseEntityExceptionHandler {
    
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers,
            HttpStatusCode status,
            WebRequest request) {
        
        ValidationErrorResponse error = new ValidationErrorResponse();
        
        ex.getBindingResult().getFieldErrors().forEach(fieldError -> 
            error.getViolations().add(
                new Violation(fieldError.getField(), fieldError.getDefaultMessage())
            )
        );
        
        return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
    }
}

@Valid vs @Validated

Understanding the difference between these annotations is crucial:¹⁰¹⁵¹⁶

@Valid:

Part of Jakarta Bean Validation (JSR 380)
Used for triggering validation on method parameters, especially @RequestBody
Can be used on nested objects for cascading validation
Does not support validation groups

@Validated:

Spring-specific annotation
Extends @Valid functionality with validation groups support
Required at class level for method parameter validation (path variables, request parameters)
Supports grouping constraints for different scenarios (create vs update)

Example with Validation Groups:¹⁵⁹

// Define validation groups
public interface OnCreate {}
public interface OnUpdate {}

public class User {
    
    @Null(groups = OnCreate.class)
    @NotNull(groups = OnUpdate.class)
    private Long id;
    
    @NotBlank(groups = {OnCreate.class, OnUpdate.class})
    private String username;
    
    // Other fields
}

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @PostMapping
    public ResponseEntity<User> createUser(
            @Validated(OnCreate.class) @RequestBody User user) {
        // Create logic
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(
            @PathVariable Long id,
            @Validated(OnUpdate.class) @RequestBody User user) {
        // Update logic
    }
}

Creating Custom Validation Annotations

For complex validation logic not covered by built-in annotations, create custom validators:¹⁷¹⁸¹⁹⁹

Step 1: Create the Annotation:¹⁹¹⁷

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneNumberValidator.class)
@Documented
public @interface ValidPhoneNumber {
    
    String message() default "Invalid phone number format";
    
    Class<?>[] groups() default {};
    
    Class<? extends Payload>[] payload() default {};
}

Step 2: Implement the Validator:¹⁷¹⁹

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

public class PhoneNumberValidator implements ConstraintValidator<ValidPhoneNumber, String> {
    
    @Override
    public void initialize(ValidPhoneNumber constraintAnnotation) {
        // Initialization logic if needed
    }
    
    @Override
    public boolean isValid(String phoneNumber, ConstraintValidatorContext context) {
        if (phoneNumber == null) {
            return true; // Use @NotNull for null checks
        }
        
        // Custom validation logic
        return phoneNumber.matches("^\\+?[1-9]\\d{9,14}quot;);
    }
}

Step 3: Use the Custom Annotation:¹⁹¹⁷

public class ContactInfo {
    
    @ValidPhoneNumber(message = "Phone number must be in international format")
    private String phoneNumber;
    
    // Other fields
}

Class-Level Validation for Cross-Field Dependencies:¹⁹

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordMatchesValidator.class)
public @interface PasswordMatches {
    String message() default "Passwords do not match";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class PasswordMatchesValidator implements ConstraintValidator<PasswordMatches, UserRegistrationDto> {
    
    @Override
    public boolean isValid(UserRegistrationDto dto, ConstraintValidatorContext context) {
        return dto.getPassword() != null && dto.getPassword().equals(dto.getConfirmPassword());
    }
}

@PasswordMatches
public class UserRegistrationDto {
    private String password;
    private String confirmPassword;
    // Other fields
}

Testing Validation and Exception Handling

Verify your validation and exception handling work correctly with integration tests:⁹

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(EmployeeController.class)
class EmployeeControllerTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @Test
    void whenInputIsInvalid_thenReturns400() throws Exception {
        String invalidEmployee = "{\"firstName\":\"\",\"email\":\"invalid-email\"}";
        
        mockMvc.perform(post("/api/employees")
                .contentType(MediaType.APPLICATION_JSON)
                .content(invalidEmployee))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.violations").isArray());
    }
    
    @Test
    void whenResourceNotFound_thenReturns404() throws Exception {
        mockMvc.perform(get("/api/employees/999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.statusCode").value(404));
    }
}

Best Practices

Centralize Exception Handling: Use @RestControllerAdvice to avoid repetitive try-catch blocks in controllers²⁰⁷³
Provide Meaningful Error Messages: Include field names, validation constraints, and clear descriptions⁷¹⁹
Use Appropriate HTTP Status Codes: 400 for validation errors, 404 for not found, 500 for server errors³⁷
Validate Early: Validate input at the controller layer before processing business logic²⁹
Don't Expose Sensitive Information: Avoid including stack traces or internal details in production error responses¹⁷
Return Consistent Error Structures: Define a standard error response format for all APIs⁷³
Use @Valid on Nested Objects: Apply @Valid to nested complex types for cascading validation⁹
Separate Validation from Business Logic: Keep validation constraints declarative using annotations rather than mixing with code²⁹

By implementing these patterns, you create robust, maintainable REST APIs with comprehensive error handling and validation in Spring Boot. The combination of @RestControllerAdvice, @ExceptionHandler, and @Valid provides a powerful, declarative approach to managing exceptions and ensuring data integrity across your application.⁶¹³³⁷²⁹ <span style="display:none">²¹²²²³²⁴²⁵²⁶²⁷²⁸²⁹³⁰³¹³²³³³⁴³⁵³⁶³⁷³⁸³⁹⁴⁰⁴¹⁴²⁴³⁴⁴⁴⁵⁴⁶⁴⁷⁴⁸⁴⁹⁵⁰⁵¹⁵²⁵³⁵⁴⁵⁵⁵⁶⁵⁷⁵⁸⁵⁹⁶⁰⁶¹⁶²⁶³⁶⁴⁶⁵⁶⁶⁶⁷⁶⁸⁶⁹⁷⁰⁷¹⁷²⁷³⁷⁴⁷⁵⁷⁶⁷⁷⁷⁸⁷⁹⁸⁰⁸¹⁸²⁸³⁸⁴⁸⁵⁸⁶⁸⁷⁸⁸⁸⁹⁹⁰⁹¹⁹²⁹³</span>