Spring Rest Service Exception Handling

Last article, we created our very first Spring Boot REST Web Service. In this tutorial lets concentrate Spring Rest Service Exception Handling.


  1. Manual Way. Handle exceptions and Response Status on your own
  2. Controller Advice
  3. Use @ResponseStatus with Custom Runtime Exception.

1 Manually Handling Exceptions

In the Spring Boot Rest Service tutorials we had created a Dogs Service to understand the concepts. In this post lets extend the same Dogs Service to handle exceptions.

The DogsController returns a ResponseEntity instance which has a response body along with HttpStatus. If no exception is thrown the below endpoint returns List<Dog> as response body and 200 as status.

For DogsNotFoundException it returns empty body and status 404.

For DogsServiceException it returns 500 and empty body.

The problem with this approach is Duplication. The catch blocks are generic and will be needed in other endpoints as well (e.g. DELETE, POST etc).

2 Controller Advice

Spring provides a better way of handling exceptions which is Controller Advice. This is a centralised place to handle all the application level exceptions.

Our Dogs Controller now looks clean and it is free for any sort of handling exceptions.

2.1 Handle and set Response Status

Below is our @ControllerAdvice class where we are handling all the exceptions.

See what is happening here:

handleRunTimeException: This method handles all the RuntimeException and returns status of INTERNAL_SERVER_ERROR.
handleNotFoundException: This method handles DogsNotFoundException and returns NOT_FOUND.
handleDogsServiceException: This method handles DogsServiceException and returns INTERNAL_SERVER_ERROR.

The key is catch the checked exceptions in the application and throw RuntimeExceptions. Let these exceptions be thrown out of Controller class and then Spring applies ControllerAdvice to it.

2.2 Use @ResponseStatus to map exception to ResponseStatus

Another short way to do achieve this is to use @ResponseStatus. It looks simpler and more readable.

Have a look at the second handler. We can group multiple similar exception and map a common Response Code for them.

3 Use @ResponseStatus with Custom Exception

Spring also does abstraction for @ControllerAdvice and we can even skip writing one.
The trick is define your own RunTimeException and annotate it with a specific @ResponseStatus. When the particular exception is thrown out of a Controller spring abstraction returns the specific Response Status.

Here is a custom RunTimeException class.

Let’s throw it from anywhere in the code. For example, I am throwing it from a Service method here

I made a call to the respective Controller endpoint and I receive 404 with below body.

Interesting to see is, my exception message is correctly propagated in the response body.

4 Summary

So in this Spring Rest Service Exception Handling tutorial we have seen how to handle exception with Spring Web Application. Spring’s exception abstraction frees you from writing those repeating bulky catch blocks and really improve the readability with the help of annotations.

I am Technology enthusiast who loves to learn and adapt to newer programming practices and trends, and have huge passion for sharing what I know.
I work as a Technology Lead in Java Platform, and have little more than a decade of experience in Design, Code, Refactor, Test, and Deploy large scale applications as well as micro-services.
Apart from programming, I love Photography, Music creation, Fictions, Ghazals and Cooking. If you share any of the common interests, feel free to buzz. You comments, suggestions, and appreciations are always welcome.

Leave a Reply

Your email address will not be published. Required fields are marked *