Unified Exception Handling in Spring Boot: Principles, Implementation, and Best Practices

In modern Java backend development, handling exceptions with repetitive try { ... } catch { ... } finally { ... } blocks leads to noisy code and reduced readability. This article introduces a clean approach that replaces scattered try‑catch statements with a unified exception handling mechanism.

The core idea is to use Spring's @ControllerAdvice together with @ExceptionHandler to capture exceptions thrown from any controller or service layer, and to return a consistent error response containing a code and message field.

To avoid defining a separate exception class for each error scenario, the article proposes a combination of a custom Assert interface and an enum that implements both Assert and a response‑code interface. Example snippets:

public abstract class Assert {
    public static void notNull(Object obj, String message) {
        if (obj == null) {
            throw new IllegalArgumentException(message);
        }
    }
}

Enum definition that carries an error code and message:

public enum ResponseEnum implements BusinessExceptionAssert {
    BAD_LICENCE_TYPE(7001, "Bad licence type."),
    LICENCE_NOT_FOUND(7002, "Licence not found.");
    private final int code;
    private final String message;
    // getters and constructors omitted for brevity
}

Using the enum as an assertion:

ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence);
ResponseEnum.BAD_LICENCE_TYPE.assertNotNull(licenceTypeEnum);

The unified exception handler class is annotated with @ControllerAdvice and defines multiple @ExceptionHandler methods to process:

Business exceptions ( BusinessException )

Base custom exceptions ( BaseException )

Servlet‑related exceptions such as NoHandlerFoundException , HttpRequestMethodNotSupportedException , etc.

Parameter binding and validation errors ( BindException , MethodArgumentNotValidException )

All other uncaught exceptions

Each handler logs the error and builds an ErrorResponse object. In production environments, generic messages are returned to avoid exposing internal details.

The article also explains how to configure Spring to throw an exception for 404 errors instead of the default Whitelabel page:

spring.mvc.throw-exception-if-no-handler-found=true
spring.resources.add-mappings=false

A unified response format is defined with a base class containing code and message , and subclasses for successful data payloads ( CommonResponse ) and paginated results ( QueryDataResponse ). Helper classes R and QR simplify response creation.

Practical validation is demonstrated with a sample LicenceService that uses the custom assertions and the unified handler to return clear error codes for missing licences, invalid licence types, and database errors.

Finally, the article summarizes the benefits of combining assertions, enums, and a global exception handler: reduced boilerplate, consistent error codes, easier internationalization, and cleaner business logic.