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

In modern Java backend development, handling numerous try‑catch blocks leads to redundant and hard‑to‑read code; a unified exception handling approach can dramatically simplify error management.

What is unified exception handling? Spring 3.2 introduced @ControllerAdvice and @ExceptionHandler , allowing developers to define exception‑handling methods once and apply them to all controllers, separating business logic from error handling.

The solution combines a custom Assert interface with an IResponseEnum that supplies an error code and message . Implementations such as BusinessExceptionAssert generate specific BusinessException instances based on enum values, eliminating the need for a separate exception class per error case.

public interface Assert {
    default void assertNotNull(Object obj) {
        if (obj == null) {
            throw new IllegalArgumentException("Object must not be null");
        }
    }
}

public interface IResponseEnum {
    int getCode();
    String getMessage();
}

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 omitted for brevity
}

The central UnifiedExceptionHandler class, annotated with @ControllerAdvice , defines several @ExceptionHandler methods:

handleBusinessException – processes custom business exceptions.

handleBaseException – handles other BaseException subclasses.

handleServletException – catches framework‑level errors such as NoHandlerFoundException , HttpRequestMethodNotSupportedException , etc., mapping them to a unified error response.

handleBindException and handleValidException – aggregate validation errors into a single readable message.

handleException – a fallback for any unexpected exception, optionally hiding details in production environments.

All handlers return a standardized ErrorResponse containing code and message . The article also defines common response wrappers ( BaseResponse , CommonResponse , QueryDataResponse ) and short aliases ( R , QR ) for convenient API responses.

Testing demonstrates how the framework captures missing resources, invalid request parameters, unsupported HTTP methods, and database errors, returning consistent JSON payloads regardless of the underlying exception type.

In production, the handler can replace detailed stack traces with a generic "Network error" message to avoid exposing internal details, while still logging the full exception for developers.

Overall, the article shows how to achieve clean, maintainable error handling in Spring Boot by leveraging annotations, enums, and a unified response model.