Error Handling Spring Boot Starter

The library provides specialized handling for validation exceptions like MethodArgumentNotValidException and ConstraintViolationException. When validation fails, the JSON response includes a code (VALIDATION_FAILED), a message summarizing the errors, and arrays for fieldErrors, parameterErrors, or globalErrors depending on where the validation occurred.

• fieldErrors: Errors on specific properties of a request body.
• parameterErrors: Errors on @RequestParam or other method parameters.
• globalErrors: Errors on the class level (e.g., custom class-level constraints).

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed for object='exampleRequestBody'. Error count: 2",
  "fieldErrors": [
    {
      "code": "INVALID_SIZE",
      "property": "name",
      "message": "size must be between 10 and 2147483647",
      "rejectedValue": "",
      "path": "name"
    }
  ]
}

By default, the library does not provide a response for unauthorized exceptions. To use the library's error handling for authentication failures, you must define io.github.wimdeblauwe.errorhandlingspringbootstarter.UnauthorizedEntryPoint as a Spring bean and set it as the entry point in your SecurityFilterChain.

import io.github.wimdeblauwe.errorhandlingspringbootstarter.UnauthorizedEntryPoint;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.ErrorCodeMapper;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.ErrorMessageMapper;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.HttpStatusMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import com.fasterxml.jackson.databind.ObjectMapper;

public class WebSecurityConfiguration {
    @Bean
    public UnauthorizedEntryPoint unauthorizedEntryPoint(HttpStatusMapper httpStatusMapper, 
                                                         ErrorCodeMapper errorCodeMapper, 
                                                         ErrorMessageMapper errorMessageMapper, 
                                                         ObjectMapper objectMapper) {
        return new UnauthorizedEntryPoint(httpStatusMapper, errorCodeMapper, errorMessageMapper, objectMapper);
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http, UnauthorizedEntryPoint unauthorizedEntryPoint) throws Exception {
        http.httpBasic(customizer -> customizer.disable());
        http.authorizeHttpRequests(customizer -> customizer.anyRequest().authenticated());
        http.exceptionHandling(customizer -> customizer.authenticationEntryPoint(unauthorizedEntryPoint));
        return http.build();
    }
}

The library defaults to only handling exceptions from @RestController classes. To support exceptions that occur before reaching a controller (like HttpRequestMethodNotSupportedException), you must define a custom @ControllerAdvice that extends io.github.wimdeblauwe.errorhandlingspringbootstarter.servlet.ErrorHandlingControllerAdvice.

import io.github.wimdeblauwe.errorhandlingspringbootstarter.servlet.ErrorHandlingControllerAdvice;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.ApiExceptionHandler;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.FallbackApiExceptionHandler;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.LoggingService;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.web.bind.annotation.ControllerAdvice;
import java.util.List;

@ControllerAdvice
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class FallbackExceptionHandler extends ErrorHandlingControllerAdvice {

    public FallbackExceptionHandler(List<ApiExceptionHandler> handlers, 
                                    FallbackApiExceptionHandler fallbackHandler, 
                                    LoggingService loggingService) {
        super(handlers, fallbackHandler, loggingService);
    }
}

To handle access denied exceptions using the library, define io.github.wimdeblauwe.errorhandlingspringbootstarter.ApiErrorResponseAccessDeniedHandler as a Spring bean and register it in your SecurityFilterChain.

import io.github.wimdeblauwe.errorhandlingspringbootstarter.ApiErrorResponseAccessDeniedHandler;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.ErrorCodeMapper;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.ErrorMessageMapper;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.mapper.HttpStatusMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.access.AccessDeniedHandler;
import com.fasterxml.jackson.databind.ObjectMapper;

public class WebSecurityConfiguration {

    @Bean
    public AccessDeniedHandler accessDeniedHandler(HttpStatusMapper httpStatusMapper, 
                                                    ErrorCodeMapper errorCodeMapper, 
                                                    ErrorMessageMapper errorMessageMapper, 
                                                    ObjectMapper objectMapper) {
        return new ApiErrorResponseAccessDeniedHandler(objectMapper, httpStatusMapper, errorCodeMapper, errorMessageMapper);
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http, AccessDeniedHandler accessDeniedHandler) throws Exception {
        http.httpBasic(customizer -> customizer.disable());
        http.authorizeHttpRequests(customizer -> customizer.anyRequest().authenticated());
        http.exceptionHandling(customizer -> customizer.accessDeniedHandler(accessDeniedHandler));
        return http.build();
    }
}

The library generates error codes based on the exception class name. You can customize this behavior:

• Change Strategy: Set error.handling.default-error-code-strategy=FULL_QUALIFIED_NAME to use the full class name instead of the default ALL_CAPS style.
• Global Override: Use error.handling.codes.<fully-qualified-exception-name>=<CUSTOM_CODE> to override codes for specific exceptions globally.
• Per-Class Override: Use the @ResponseErrorCode("CUSTOM_CODE") annotation on your exception class.
• Validation Overrides: Override specific validation annotation codes using error.handling.codes.<AnnotationName>=<CODE> (e.g., error.handling.codes.Size=SIZE_REQUIREMENT_NOT_MET).
• Field-Specific Validation Overrides: Use error.handling.codes.<fieldName>.<AnnotationName>=<CODE> to target a specific field (e.g., error.handling.codes.password.Pattern=PASSWORD_COMPLEXITY_REQUIREMENTS_NOT_MET).

error.handling.default-error-code-strategy=FULL_QUALIFIED_NAME
error.handling.codes.java.lang.IllegalArgumentException=ILLEGAL_ARGUMENT
error.handling.codes.password.Pattern=PASSWORD_COMPLEXITY_REQUIREMENTS_NOT_MET

Override the default exception message in the JSON response using the error.handling.messages property:

• Exception Override: error.handling.messages.<fully-qualified-exception-name>=<Custom Message>
• Validation Annotation Override: error.handling.messages.<AnnotationName>=<Custom Message> (e.g., error.handling.messages.NotBlank=The property should not be blank).
• Field-Specific Override: error.handling.messages.<fieldName>.<AnnotationName>=<Custom Message> (e.g., error.handling.messages.password.Pattern=The password complexity rules are not met.).

Superclass Hierarchy Search: If error.handling.search-super-class-hierarchy=true is set, the library will search up the exception hierarchy for matching configuration. You can reset messaging to default for a specific subclass by providing an empty value: error.handling.messages.my.ApplicationException=.

error.handling.messages.com.company.application.user.UserNotFoundException=The user was not found
error.handling.messages.NotBlank=The property should not be blank
error.handling.messages.password.Pattern=The password complexity rules are not met.