Exception Handling for REST with Spring 3.2

1. Overview

This article will focus on how to implement Exception Handling with Spring for a REST API. We’ll look at the older solutions available before Spring 3.2 and then at the new Spring 3.2 support.

The main goal of this article is to show how to best map Exceptions in the application to HTTP Status Codes. Which status codes are suitable for which scenarios is not in the scope of this article, neither is the syntax of REST Error Representation.

Before Spring 3.2, the two main approaches to handling exceptions in a Spring MVC application were: HandlerExceptionResolver and the @ExceptionHandler annotation. Spring 3.2 introduced the new @ControllerAdvice annotation to address the limitations of the previous two solutions.

All of these do have one thing in common – they deal with the separation of concerns very well: the standard application code can throw exception normally to indicate a failure of some kind – exceptions which will then be handled via any of the following.

2. Via Controller level @ExceptionHandler

Defining a Controller level method annotated with @ExceptionHandler is very easy:

public class FooController{
    @ExceptionHandler({ CustomException1.class, CustomException2.class })
    public void handleException() {

That’s all well and good, but this approach does have one major drawback – the @ExceptionHandler annotated method is only active for that particular Controller, not globally for the entire application. Of course, this makes it not well suited for a generic exception handling mechanism.

A common solution for this is to have all Controllers in the application extending a Base Controller class – however, this can be a problem for applications where, for whatever reasons, the Controllers cannot be made to extend from such a class. For example, the Controllers may already extend from another base class which may be in another jar or not directly modifiable, or may themselves not be directly modifiable.

Next, we’ll look at another way to solve the exception handling problem – one that is global and does not include any changes to existing artifacts such as Controllers.

3. Via HandlerExceptionResolver

In order to implement a uniform exception handling mechanism in our REST API, we’ll need to work with an HandlerExceptionResolver – this will resolve any exceptions thrown at runtime by the application. Before going for a custom resolver, let’s go over the existing implementations.

3.1. ExceptionHandlerExceptionResolver

This resolver was introduced in Spring 3.1 and is enabled by default in the DispatcherServlet. This is actually the core component of how the @ExceptionHandler mechanism presented earlier works.

3.2. DefaultHandlerExceptionResolver

This resolver was introduced in Spring 3.0 and is enabled by default in the DispatcherServlet. It is used to resolve standard Spring exceptions to their corresponding HTTP Status Codes, namely Client error – 4xx and Server error – 5xx status codes. Here is the full list of the Spring Exceptions it handles, and how these are mapped to status codes.

While it does set the Status Code of the Response properly, one limitation of this resolver is that it doesn’t set anything to the body of the Response. However, in the context of a REST API, the Status Code is really not enough information to present to the Client – the response has to have a body as well, to allow the application to give additional information about the cause of the failure.

This can be solved by configuring View resolution and rendering error content through ModelAndView, but the solution is clearly not optimal – which is why a better option has been made available with Spring 3.2 – we’ll talk about that in the latter part of this article.

3.3. ResponseStatusExceptionResolver

This resolver was also introduced in Spring 3.0 and is enabled by default in the DispatcherServlet. It’s main responsibility is to use the @ResponseStatus annotation available on custom exceptions and to map these exceptions to HTTP status codes.

Such a custom exception may look like:

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public final class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException() {
    public ResourceNotFoundException(String message, Throwable cause) {
        super(message, cause);
    public ResourceNotFoundException(String message) {
    public ResourceNotFoundException(Throwable cause) {

Same as the DefaultHandlerExceptionResolver, this resolver is limited in the way it deals with the body of the response – it does map the Status Code on the response, but the body is still null.

3.4. SimpleMappingExceptionResolver and AnnotationMethodHandlerExceptionResolver

The SimpleMappingExceptionResolver has been around for quite some time – it comes out of the older Spring MVC model and is not very relevant for a REST Service. It is used to map exception class names to view names.

The AnnotationMethodHandlerExceptionResolver was introduced in Spring 3.0 to handle exceptions through the @ExceptionHandler annotation, but has been deprecated by ExceptionHandlerExceptionResolver as of Spring 3.2.

3.5. Custom HandlerExceptionResolver

The combination of DefaultHandlerExceptionResolver and ResponseStatusExceptionResolver goes a long way towards providing a good error handling mechanism for a Spring RESTful Service – but the major limitation – no control over the body of the response – justifies creating a new exception resolver.

So, one goal for the new resolver is to enable setting a more informative response body – one that would also conform to the type of representation requested by the client (as specified by the Accept header):

public class RestResponseStatusExceptionResolver extends AbstractHandlerExceptionResolver {

    protected ModelAndView doResolveException
      (HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        try {
            if (ex instanceof IllegalArgumentException) {
                return handleIllegalArgument((IllegalArgumentException) ex, response, handler);
        } catch (Exception handlerException) {
            logger.warn("Handling of [" + ex.getClass().getName() + "] 
              resulted in Exception", handlerException);
        return null;

    private ModelAndView handleIllegalArgument
      (IllegalArgumentException ex, HttpServletResponse response) throws IOException {
        String accept = request.getHeader(HttpHeaders.ACCEPT);
        return new ModelAndView();

One detail to notice here is the Request itself is available, so the application can consider the value of the Accept header sent by the client. For example, if the client asks for application/json then, in case of an error condition, the application should still return a response body encoded with application/json.

The other important implementation detail is that a ModelAndView is returned – this is the body of the response and it will allow the application to set whatever is necessary on it.

This approach is a consistent and easily configurable mechanism for the error handling of a Spring REST Service. It is does however have limitations: it’s interacting with the low level HtttpServletResponse and it fits into the old MVC model which uses ModelAndView – so there’s still room for improvement.

4. Via new @ControllerAdvice (Spring 3.2 Only)

Spring 3.2 brings support for a global @ExceptionHandler with the new @ControllerAdvice annotation. This enables a mechanism that breaks away from the older MVC model and makes use of ResponseEntity along with the type safety and flexibility of @ExceptionHandler:

public class RestResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(value = { IllegalArgumentException.class, IllegalStateException.class })
    protected ResponseEntity<Object> handleConflict(RuntimeException ex, WebRequest request) {
        String bodyOfResponse = "This should be application specific";
        return handleExceptionInternal(ex, bodyOfResponse, 
          new HttpHeaders(), HttpStatus.CONFLICT, request);

The new annotation allows the multiple scattered @ExceptionHandler from before to be consolidated into a single, global error handling component.

The actual mechanism is extremely simple but also very flexible:

  • it allows full control over the body of the response as well as the status code
  • it allows mapping of several exceptions to the same method, to be handled together
  • it makes good use of the newer RESTful ResposeEntity response

5. Conclusion

This tutorial discussed several ways to implement an exception handling mechanism for a REST API in Spring, starting with the older mechanism and continuing with the new Spring 3.2 support. For a full implementation of these exception handling mechanisms working in a real-world REST Service, check out the github project.

Reference: Error Handling for REST with Spring 3 from our JCG partner Eugen Paraschiv at the baeldung blog.
Related Whitepaper:

Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions

Get ready to program in a whole new way!

Functional Programming in Java will help you quickly get on top of the new, essential Java 8 language features and the functional style that will change and improve your code. This short, targeted book will help you make the paradigm shift from the old imperative way to a less error-prone, more elegant, and concise coding style that’s also a breeze to parallelize. You’ll explore the syntax and semantics of lambda expressions, method and constructor references, and functional interfaces. You’ll design and write applications better using the new standards in Java 8 and the JDK.

Get it Now!  

One Response to "Exception Handling for REST with Spring 3.2"

  1. A great post! Thanks for putting this together. You had some insights for me. I have dealt with this problem myself and have a related post at http://www.lopakalogic.com/articles/web-services-articles/advanced-error-handling-rest-based-web-service/

Leave a Reply

two + = 4

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books