How to implement exception handling in a mixed MVC and REST Spring application?

Spring Boot 3.2.x / Spring Web 6.1.x

In an app with both MVC controllers (returning HTML pages via JSP) and REST controllers, how can I implement global exception handling such that MVC controller methods result in an error page while REST endpoints return non-page responses (400, 404, 500, etc with text or JSON response body)?

I have a @ControllerAdvice implemented that handles various kinds of exceptions with specific @ExceptionHandler and @ResponseStatus annotations. These methods all return a page (eg, "forward:/error") as they should for MVC requests.

Here's part of that class:

@ControllerAdvice
public class GlobalDefaultExceptionHandler {

    //...other methods...

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public String defaultInternalErrorHandler(Model model, Exception e, HttpServletRequest req) {
        UUID errorID = UUID.randomUUID();
        log.error(errorID + " | Unhandled exception processing request to " + req.getRequestURI(), e);

        model.addAttribute("exception", e);
        model.addAttribute("errorID", errorID);
        return "forward:/error";
    }

}

This is the "fallback" handler method if none of the others handle the exception that's thrown. This works great for all the MVC controller methods that return pages (HTML).

However, I don't want REST controller endpoints to return HTML content, they should return (JSON in my case) content with an appropriate HTTP response status (eg, 400 for invalid requests, 500 for server errors, etc).

I've tried adding another @RestControllerAdvice class similar to this:

@RestControllerAdvice
@Slf4j
public class GlobalRestExceptionHandler {

    @ExceptionHandler(ServletRequestBindingException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String handle(ServletRequestBindingException e, HttpServletRequest req) {
        defaultInternalErrorHandler(e, req);
        return "Invalid Request: " + e.getMessage();
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public String defaultInternalErrorHandler(Exception e, HttpServletRequest req) {
        UUID errorID = UUID.randomUUID();
        log.error(errorID + " | Unhandled exception processing API request to " + req.getRequestURI(), e);
        return "Server error: " + e;
    }
}

Unfortunately, that class doesn't seem to be used. Any exception from a REST endpoint is flowing through the @ControllerAdvice default method and returning the error page.

How can I have the best of both worlds, MVC requests going to the error page and REST endpoints returning REST-friendly (JSON) content?

This is supported by the Advice interfaces themselves, and they each provide two means of pulling this off.

You can either differentiate the two by the packages they're in, or by their Controller annotation.

So, if your classes are separated by packages like com.myapp.controller.web and com.myapp.controller.rest you can use @ControllerAdvice("com.myapp.controller.web") and @RestControllerAdvice("com.myapp.controller.rest") respectively.

If you want to let the annotations drive this, you would simply use @ControllerAdvice(annotations = Controller.class) or @RestControllerAdvice(annotations = RestController.class).

Important Note about using the annotations: Without further guidance, Spring can/will prioritize the @ControllerAdvice annotated handler over the one annotated as @RestControllerAdvice. This is because @RestController is a composite annotation that includes/extends @Controller, so when Spring is testing each advice handler to see if it applies to a given @Controller, it sees even controllers annotated as @RestController as having the @Controller annotation. That means the handler annotated as @ControllerAdvice(annotations = Controller.class) will always apply to REST controllers; if that bean happens to be ordered before the @RestControllerAdvice bean, the REST one will never get a chance to handle exceptions. See the code in org.springframework.web.method.HandlerTypePredicate.test(Class<?> controllerType).

You can work around this by prioritizing the @RestControllerAdvice(annotations = RestController.classs handler using @Order annotation (@Priority annotation as well as implementing Ordered interface are also options) so that it has a higher precedence than the default. See this answer for a discussion of the ordering.

Here's an example of a a pair of exception handling advice classes that uses this technique:

@ControllerAdvice(annotations = Controller.class)
public class GlobalDefaultExceptionHandler {

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public String handle(Model model, Exception e, HttpServletRequest req) {
        UUID errorID = UUID.randomUUID();
        log.error(errorID + " | Unhandled exception processing page request to " + req.getRequestURI(), e);

        model.addAttribute("exception", e);
        model.addAttribute("errorID", errorID);
        return "forward:/error";
    }
}


@RestControllerAdvice(annotations = RestController.class)
@Order(0)
public class RESTExceptionHandler {

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public String handle(Exception e, HttpServletRequest req) {
        UUID errorID = UUID.randomUUID();
        log.error(errorID + " | Unhandled exception processing API request to " + req.getRequestURI(), e);

        return "Unhandled exception: " + e;
    }
}