Spring Rest Service Exception Handling

Learn How to Handle Exceptions and Spring REST Service and return correct HTTP Response Status Codes.

Overview

This tutorial talks about Spring Rest Service Exception Handling. Last article, we created our very first Spring Boot Rest Service. In this tutorial let’s concentrate on how to handle exception in Spring Applications. While, there always is an option to handle them manually and set a particular ResposeStatus. However Spring provides an abstraction over entire exception handling and just asks you to put a few annotations and it takes care of everything else. In this article we will see it happening with code examples. 

Manually Handle 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.

package com.amitph.spring.dogs.web;

import com.amitph.spring.dogs.model.DogDto;
import com.amitph.spring.dogs.repo.Dog;
import com.amitph.spring.dogs.service.DogsService;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/dogs")
@RequiredArgsConstructor
@Setter
public class DogsController {
    @Autowired private final DogsService service;

    @GetMapping
    public ResponseEntity<List<Dog>> getDogs() {
        List<Dog> dogs;

        try {
            dogs = service.getDogs();
        } catch (DogsServiceException ex) {
            return new ResponseEntity<>(null, null, HttpStatus.INTERNAL_SERVER_ERROR);
        } catch (DogsNotFoundException ex) {
            return new ResponseEntity<>(null, null, HttpStatus.NOT_FOUND);
        }
        return new ResponseEntity<>(dogs, HttpStatus.OK);
    }
}Code language: Java (java)

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).

Controller Advice (@ControllerAdvice)

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.

package com.amitph.spring.dogs.web;

import com.amitph.spring.dogs.model.DogDto;
import com.amitph.spring.dogs.repo.Dog;
import com.amitph.spring.dogs.service.DogsService;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/dogs")
@RequiredArgsConstructor
@Setter
public class DogsController {
    @Autowired private final DogsService service;

    @GetMapping
    public ResponseEntity<List<Dog>> getDogs() {
        return new ResponseEntity<>(service.getDogs(), HttpStatus.OK);
    }
}Code language: Java (java)

Handle and set Response Status

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

package com.amitph.spring.dogs.web;

import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR;
import static org.springframework.http.HttpStatus.NOT_FOUND;

@ControllerAdvice
@Slf4j
public class DogsServiceErrorAdvice {

    @ExceptionHandler({RuntimeException.class})
    public ResponseEntity<String> handleRunTimeException(RuntimeException e) {
        return error(INTERNAL_SERVER_ERROR, e);
    }

    @ExceptionHandler({DogsNotFoundException.class})
    public ResponseEntity<String> handleNotFoundException(DogsNotFoundException e) {
        return error(NOT_FOUND, e);
    }

    @ExceptionHandler({DogsServiceException.class})
    public ResponseEntity<String> handleDogsServiceException(DogsServiceException e){
        return error(INTERNAL_SERVER_ERROR, e);
    }

    private ResponseEntity<String> error(HttpStatus status, Exception e) {
        log.error("Exception : ", e);
        return ResponseEntity.status(status).body(e.getMessage());
    }
}Code language: Java (java)

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.

try {
    //
    // Lines of code
    //
} catch (SQLException sqle) {
    throw new DogsServiceException(sqle.getMessage());
}Code language: Java (java)

Use @ResponseStatus to map exception to ResponseStatus

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

package com.amitph.spring.dogs.web;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

@ControllerAdvice
public class DogsServiceErrorAdvice {

    @ResponseStatus(HttpStatus.NOT_FOUND)
    @ExceptionHandler({DogsNotFoundException.class})
    public void handle(DogsNotFoundException e) {}

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler({DogsServiceException.class, SQLException.class, NullPointerException.class})
    public void handle() {}

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler({DogsServiceValidationException.class})
    public void handle(DogsServiceValidationException e) {}
}Code language: Java (java)

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

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.

package com.amitph.spring.dogs.service;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(HttpStatus.NOT_FOUND)
public class DogsNotFoundException extends RuntimeException {
    public DogsNotFoundException(String message) {
        super(message);
    }
}Code language: Java (java)

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

public List<Dog> getDogs() {
    throw new DogsNotFoundException("No Dog Found Here..");
}Code language: Java (java)

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

{
    "timestamp": "2018-11-28T05:06:28.460+0000",
    "status": 404,
    "error": "Not Found",
    "message": "No Dog Found Here..",
    "path": "/dogs"
}Code language: JSON / JSON with Comments (json)

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

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.

For more on Spring and Spring Boot, please visit Spring Tutorials.

---