Validation error response formatting in Spring Boot

Introduction

When users send wrong data, we want to tell them clearly what is wrong. Formatting validation error responses helps users fix their mistakes easily.

When a user submits a form with missing or wrong information.

When an API receives invalid data and needs to explain the errors.

When you want to keep error messages consistent and easy to read.

When you want to help frontend apps show clear error messages to users.

Syntax

Spring Boot

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.RestControllerAdvice;
import java.util.Map;
import java.util.HashMap;

@RestControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ValidationErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        ValidationErrorResponse errors = new ValidationErrorResponse();
        ex.getBindingResult().getFieldErrors().forEach(error -> {
            String fieldName = error.getField();
            String errorMessage = error.getDefaultMessage();
            errors.addError(fieldName, errorMessage);
        });
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

class ValidationErrorResponse {
    private Map<String, String> errors = new HashMap<>();

    public void addError(String field, String message) {
        errors.put(field, message);
    }

    public Map<String, String> getErrors() {
        return errors;
    }
}

This code uses @RestControllerAdvice to catch validation errors globally.

The MethodArgumentNotValidException contains details about which fields failed validation.

Examples

This example returns a simple map of field names to error messages as JSON.

Spring Boot

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    ex.getBindingResult().getFieldErrors().forEach(error ->
        errors.put(error.getField(), error.getDefaultMessage())
    );
    return ResponseEntity.badRequest().body(errors);
}

This example uses Java records to create a structured error response with a list of errors.

Spring Boot

public record ValidationError(String field, String message) {}

public record ValidationErrorResponse(List<ValidationError> errors) {}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ValidationErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
    List<ValidationError> errorList = ex.getBindingResult().getFieldErrors().stream()
        .map(error -> new ValidationError(error.getField(), error.getDefaultMessage()))
        .toList();
    return ResponseEntity.badRequest().body(new ValidationErrorResponse(errorList));
}

Sample Program

This Spring Boot app has a UserController that accepts a user with a name. The name must not be blank.

If the user sends an empty name, the ValidationExceptionHandler catches the error and returns a JSON with the field and message.

Spring Boot

package com.example.demo;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.Valid;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
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.*;

import java.util.HashMap;
import java.util.Map;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
@RequestMapping("/users")
class UserController {

    @PostMapping
    public String createUser(@RequestBody @Valid User user) {
        return "User created: " + user.name();
    }
}

record User(@NotBlank(message = "Name must not be blank") String name) {}

@RestControllerAdvice
class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        for (FieldError error : ex.getBindingResult().getFieldErrors()) {
            errors.put(error.getField(), error.getDefaultMessage());
        }
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

Important Notes

Always use @Valid on method parameters to trigger validation.

Customize error messages in your validation annotations for clearer feedback.

Return HTTP 400 (Bad Request) status for validation errors to follow web standards.

Summary

Validation error formatting helps users understand what went wrong.

Use @RestControllerAdvice and @ExceptionHandler to catch and format errors globally.

Return clear JSON with field names and error messages for easy frontend use.

Practice

1. What is the main purpose of formatting validation error responses in Spring Boot?

easy

A. To provide clear error messages that help users understand input mistakes

B. To speed up the application startup time

C. To reduce the size of the application package

D. To automatically fix invalid inputs

Solution

1. Step 1: Understand validation error responses

   Validation errors occur when user input does not meet rules. Formatting these errors helps users know what went wrong.

2. Step 2: Identify the purpose of formatting

   Clear error messages improve user experience by showing which fields have issues and why.

3. Final Answer:

   To provide clear error messages that help users understand input mistakes -> Option A

4. Quick Check:

   Validation error formatting = clear user messages [OK]

Hint: Errors should explain what and where input failed [OK]

Common Mistakes:

• Thinking error formatting speeds startup
• Assuming errors fix themselves automatically
• Confusing error formatting with package size

2. Which annotation is used in Spring Boot to globally handle validation exceptions and format error responses?

easy

A. @RestControllerAdvice

B. @ComponentScan

C. @Service

D. @Controller

Solution

1. Step 1: Identify global exception handling annotation

   @RestControllerAdvice is designed to handle exceptions across all controllers and format responses.

2. Step 2: Confirm other annotations are not for global error handling

   @Controller is for MVC controllers, @Service for business logic, @ComponentScan for scanning components, none handle exceptions globally.

3. Final Answer:

   @RestControllerAdvice -> Option A

4. Quick Check:

   Global error handler = @RestControllerAdvice [OK]

Hint: Use @RestControllerAdvice for global error formatting [OK]

Common Mistakes:

• Confusing @Controller with error handling
• Using @Service or @ComponentScan incorrectly
• Missing global exception handler annotation

3. Given this Spring Boot exception handler method, what will the JSON response contain when a validation error occurs?

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity> handleValidationErrors(MethodArgumentNotValidException ex) {
  Map errors = new HashMap<>();
  ex.getBindingResult().getFieldErrors().forEach(error -> {
    errors.put(error.getField(), error.getDefaultMessage());
  });
  return ResponseEntity.badRequest().body(errors);
}

medium

A. A plain text string listing all errors

B. An empty JSON object

C. A JSON object with field names as keys and error messages as values

D. A JSON array of error codes only

Solution

1. Step 1: Analyze the error map creation

   The code collects field errors and puts each field name as key and its error message as value in a Map.

2. Step 2: Understand the response body

   The Map is returned as JSON in the response body, so the client receives a JSON object with field-error pairs.

3. Final Answer:

   A JSON object with field names as keys and error messages as values -> Option C

4. Quick Check:

   Field-error map = JSON object with keys and messages [OK]

Hint: Map field to message for clear JSON error response [OK]

Common Mistakes:

• Expecting plain text instead of JSON
• Thinking response is empty or only codes
• Confusing JSON array with JSON object

4. Identify the error in this Spring Boot validation error handler method:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity> handleErrors(MethodArgumentNotValidException ex) {
  Map errors = new HashMap<>();
  for (FieldError error : ex.getBindingResult().getFieldErrors()) {
    errors.put(error.getDefaultMessage(), error.getField());
  }
  return ResponseEntity.badRequest().body(errors);
}

medium

A. The method does not handle the exception type correctly

B. The error message and field name are swapped when putting into the map

C. The response status should be OK instead of badRequest

D. The map should be a List instead

Solution

1. Step 1: Check map key-value assignment

   The code uses error.getDefaultMessage() as key and error.getField() as value, which reverses the intended field-to-message mapping.

2. Step 2: Understand correct mapping

   Field names should be keys and error messages should be values for clarity in JSON response.

3. Final Answer:

   The error message and field name are swapped when putting into the map -> Option B

4. Quick Check:

   Field as key, message as value is correct [OK]

Hint: Map field name as key, error message as value [OK]

Common Mistakes:

• Swapping keys and values in error map
• Using wrong exception class
• Returning wrong HTTP status code

5. You want to customize your Spring Boot validation error response to include the timestamp, status code, and a list of field errors with messages. Which approach correctly implements this formatting?

hard

A. Throw a new RuntimeException inside the exception handler to trigger default error page

B. Return a plain string with all errors concatenated in the exception handler

C. Use @ControllerAdvice without @ResponseBody and return a ModelAndView for errors

D. Create a custom error response class with fields for timestamp, status, and a list of errors; populate it in a @RestControllerAdvice method handling MethodArgumentNotValidException

Solution

1. Step 1: Understand desired error response structure

   The response should have timestamp, status code, and detailed field errors in JSON format.

2. Step 2: Identify correct implementation method

   Creating a custom error response class and populating it in a @RestControllerAdvice method allows structured JSON output with all required fields.

3. Step 3: Exclude incorrect options

   Returning plain strings or ModelAndView does not produce JSON with structured fields; throwing RuntimeException loses control over formatting.

4. Final Answer:

   Create a custom error response class with fields for timestamp, status, and a list of errors; populate it in a @RestControllerAdvice method handling MethodArgumentNotValidException -> Option D

5. Quick Check:

   Custom class + @RestControllerAdvice = structured JSON error [OK]

Hint: Use custom class and @RestControllerAdvice for detailed JSON errors [OK]

Common Mistakes:

• Returning plain text instead of JSON
• Using @ControllerAdvice without JSON response
• Throwing exceptions instead of formatting response