In this write-up, we are going to shed light on how to handle exceptions in Spring Boot rest API.

Why? Because exception handling brings some sort of order to errors management when unexpected scenarios occur in our applications.

In simple words, it makes our applications more resilient to errors and exceptions.

We will consider here that you are familiar with what a rest API is. Our article on how to build a rest API with Spring Boot does a great job in covering this topic.

So, let’s get started

Introduction to API Error Handling

Think about the consumer. This idea has been always one of the main core design principles for restful APIs.

So, a good rest API implementation must in one way or another promote good and clean error handling.

You may be wondering WHY?

Well, because error handling gives, in a relatively friendly manner, some hint to the consumers that something went wrong.

It gives us, as developers, the flexibility to inform the clients in a more concise way about what was wrong with the API.

In short, handling and catching our exceptions properly can incredibly improve the API’s readability and reliability.

Best Practices to Handle Exceptions

Before we dive deep into how to handle Spring Boot API exceptions, we are going to talk a little bit about best practices that can be adapted to deal with errors.

Use Meaningful Status Codes

The first step to manage errors properly is to provide the clients with human readable informations and proper HTTP status codes.

This can help the consumers to route their responses accordingly.

We should avoid returning the same HTTP status code every single time. It is a big mistake.

Pick carefully a relevant status code that reflects significantly the returned response.

Use always 2xx for successful responses, 3xx for redirections, 4xx and 5xx for error responses.

2xx (Success) indicates that the request was accepted successfully
3xx (Redirection) informs that the client must take further actions in order to complete the request
4xx (Client error) indicates an error in the request from the client side
5xx (Server error) tells that the server failed to fulfil the request

Simply put, we should not expose 500 errors to clients because they are server errors, not client errors. What happens in our servers is not the client’s business.

Use Custom Detailed Exceptions

In general, standard exceptions - called also Alien - return stack traces that are usually hard to understand.

So, this is where user-defined exceptions come to the rescue.

A rule of thumb: It is always a good practice to throw an exception that means what we want it to mean.

Wrapping an exception in a more specific class can give us more control over how we want to deal with it.

Providing our customized message can make our exception handling mechanism more meaningful and user-friendly.

Build Rest API with Spring Boot

Spring Boot is a platform of choice when it comes to building restful APIs.

So, in this section, we are going to use Spring Boot to develop a simple web application that exposes RESTful web services for users management.

The following, will be our API’s endpoints:

GET /api/users get all the users
GET /api/users/{id} retrieve a single user by ID
POST /api/users create a new user
PUT /api/users/{id} update a user's details
DELETE /api/users/{id} delete a user by ID
GET /api/user?username={username} get a user by username - this endpoint has no real value for our REST API, it is created just for testing purpose

In this tutorial, we will assume that you are familiar with the basics of Spring Boot. So, we will include code snippets without diving deep into technical details.

If it is not the case, feel free to check our tutorial about what is Spring Boot.

So, let’s get into coding

Create Spring Boot project

We are going to use Spring Initializr to scaffold and create our Spring Boot project.

To do so, you need to open your favorite browser and navigate to

Choose Maven Project, Java language, and Spring Boot version.

After that, you need to fill out the form related to Project Metadata.

Next, search for the following dependencies Web, Data JPA, MySQL, and Lombok and add them to the project.

Generate spring boot project

Now, click on the “Generate” button to download the zip file.

Finally, unzip the file and import the generated project into your favorite IDE.


This is how pom.xml of our project looks like:

        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="" xmlns:xsi="" xsi:schemaLocation="">
                <relativePath/> <!-- lookup parent from repository -->
            <description>Spring Boot Users REST API</description>





Configure MySQL Database

Spring Boot allows us to define the datasource connection parametres in the file:

        ## active Profile

        ## MicroService name

        ## Port

        ## MySQL DataSource

        ## JPA
        spring.jpa.hibernate.ddl-auto=update to set the active profile. denotes the application name.

Create Domain Model User

Now, let’s create our domain model User:

        import javax.persistence.Entity;
        import javax.persistence.GeneratedValue;
        import javax.persistence.GenerationType;
        import javax.persistence.Id;
        import javax.persistence.Table;
        import javax.validation.constraints.NotEmpty;
        import lombok.AllArgsConstructor;
        import lombok.Getter;
        import lombok.NoArgsConstructor;
        import lombok.Setter;
        import lombok.experimental.Accessors;

        @Table(name = "users")
        public class User implements Serializable {
            private static final long serialVersionUID = 1L;
            private int id;
            private String username;
            private String password;

@Getter, @Setter, @Accessors, @NoArgsConstructor, @AllArgsConstructor are Lombok annotations. They allow to generate getter and setter methods, default and all-args constructors.

Please refer to these articles for more detail:

Create User Repository Interface

Next, we need to create a custom repository for our domain model. For instance, let’s consider UserRepository:

        import java.util.Optional;
        import org.springframework.stereotype.Repository;
        import com.restapi.msusers.models.User;

        public interface UserRepository extends JpaRepository<User, Integer> {
            Optional<User> findByUsername(String username);

Create Spring Rest Controller

Lastly, we are going to create a spring controller to handle our rest API’s endpoints:

        import java.util.List;
        import javax.validation.Valid;
        import javax.validation.constraints.Min;
        import org.springframework.beans.factory.annotation.Autowired;
        import org.springframework.http.ResponseEntity;
        import org.springframework.web.bind.annotation.DeleteMapping;
        import org.springframework.web.bind.annotation.GetMapping;
        import org.springframework.web.bind.annotation.PathVariable;
        import org.springframework.web.bind.annotation.PostMapping;
        import org.springframework.web.bind.annotation.PutMapping;
        import org.springframework.web.bind.annotation.RequestBody;
        import org.springframework.web.bind.annotation.RequestMapping;
        import org.springframework.web.bind.annotation.RestController;
        import com.restapi.msusers.exceptions.ResourceNotFoundException;
        import com.restapi.msusers.models.User;
        import com.restapi.msusers.repositories.UserRepository;

        public class UserController {
            UserRepository userrepo;
            List<User> getAll(){
                return userrepo.findAll();
            ResponseEntity<User> getById(@PathVariable("id") @Min(1) int id) {
                User usr = userrepo.findById(id)
                        .orElseThrow(()->new ResourceNotFoundException("User with ID :"+id+" Not Found!"));
                return ResponseEntity.ok().body(usr);
            ResponseEntity<User> getByUsername(@RequestParam(required=true) String username) {
                User usr = userrepo.findByUsername(username)
                        .orElseThrow(()->new  ResourceNotFoundException(username+" NOT Found!"));
                return ResponseEntity.ok().body(usr);
            ResponseEntity<?> create( @Valid @RequestBody User user) {
                User addeduser =;
                URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                return ResponseEntity.created(location).build();
            ResponseEntity<User> update(@PathVariable("id")  @Min(1) int id, @Valid @RequestBody User user) {

                User puser = userrepo.findById(id)
                        .orElseThrow(()->new ResourceNotFoundException("User with ID :"+id+" Not Found!"));
                return ResponseEntity.ok().body(user);
            ResponseEntity<String> delete(@PathVariable("id") @Min(1) int id) {
                User user = userrepo.findById(id)
                        .orElseThrow(()->new ResourceNotFoundException("User with ID :"+id+" Not Found!"));
                return ResponseEntity.ok().body("User deleted with success!");      
  • ResourceNotFoundException is a custom Exception that will be thrown when the user with the given ID doesn’t exist

  • @Valid is used for validation purpose. Spring Boot automatically detect JSR 303 annotations and trigger validation of the annotated arguments

  • @Min annotation indicates that the value of the annotated parameter must be higher or equal to the specified value. If it is not the case, a validation error will be thrown

Exception Handling in Spring Boot

Spring Framework offers a host of handy ready-to-use features to help us deal with exceptions and errors in a more flexible and appropriate way.

Let’s take a close look at each option.

Using @ExceptionHandler

This annotation, as the name implies, provides a way to define methods in a particular Spring controller to specifically handle exceptions thrown by handler methods of that controller.

        public void handleSpecificException() {}

The main drawback of the @ExceptionHandler annotation is that the annotated methods will only work for the specific controller where they are defined and not for the whole application.

So, to address this limitation, Spring provides another annotation: @ControllerAdvice

Using @ControllerAdvice

Spring 3.2 comes with a brand new way to centralize the exception handling mechanism in one place.

@ControllerAdvice is mainly introduced to overcome the limitations of the @ExceptionHandler annotated: Handle exceptions globally in our applications.

With @ControllerAdvice, we can create a global handler class with multiple @ExceptionHandler methods to handle exceptions globally across the application.

        public class GlobalResponseException {
            public void handleMyException() {}

The purpose of @ControllerAdvice is to separate request handling from error handling. That way, Spring controllers become free from any sort of exception handling logic.

Using ResponseEntityExceptionHandler Class

This base class provides many methods that we can override to customize the way how we want to handle specific exceptions.

The provided methods return an instance of ResponseEntity<T>, which means that we can create and generate HTTP responses with the details (body, headers, status code) we want.

Customizing Exception Handling Using @ResponseStatus

Spring offers this annotation to bind a particular Exception to a specific HTTP response status.

So, when Spring catches that particular Exception, it generates an HTTP response with the settings defined in @ResponseStatus.

        @ResponseStatus(code = HttpStatus.BAD_REQUEST)
        class MyException extends RuntimeException {}

Handling Exception for Rest API in Practice

Now that we created a rest API using Spring Boot, let’s see how we can implement a good strategy to handle exceptions that may occur when consuming our API’s endpoints.

Create Custom Error Response

Let’s see what will happen when we try to retrieve a user that does not exist.

So, to do that, we need to call the following endpoint: GET /api/users/{id}.

This is how the output looks like:

            "timestamp": "2020-05-04T13:52:12.027+0000",
            "status": 500,
            "error": "Internal Server Error",
            "message": "User with ID :1 Not Found!",
            "path": "/api/users/1"

Well, the default error representation looks a little bit messy and misleading. Right?

500 is not the right code to describe that a requested resource is NOT FOUND. It should be 404.

Internal Server Error does not provide any meaningful information to our consumers.

Thus, exposing 500 internal server errors to the clients is not a good practice at all. Do you remember?

So, to handle our errors properly, we need to customize the default spring boot API error response with:

  • Meaningful message indicating what went wrong

  • Proper status code based on the context

  • List of errors that occurred during the requests handling

First, let’s create a new class to represent our API error response in a more relevant and user-friendly way:

        public class ApiError {
            @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd-MM-yyyy hh:mm:ss")
            private LocalDateTime timestamp;
            private HttpStatus status;
            private String message;
            private List errors;

As we can see, the name of our custom API error class is ApiError.

Create Global Exception Handler

Now, we are going to create our global handler class.

For instance, let’s consider the GlobalExceptionHandler class. We need to annotate it with @ControllerAdvice and make it extend ResponseEntityExceptionHandler.

        public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
            // define your methods here

Now, all we need to do is override ResponseEntityExceptionHandler’s methods and provide our custom exception handling implementation.

we can also define some @ExceptionHandler annotated methods to deal with some specific exceptions across the whole application.

Since the methods of ResponseEntityExceptionHandler class return ResponseEntity<T>, we need to create a helper class to map ResponseEntity objects to our custom ApiError objects.

        package com.restapi.msusers.web;
        import  org.springframework.http.ResponseEntity;

        public class ResponseEntityBuilder {
            public static ResponseEntity<Object> build(ApiError apiError) {
                  return new ResponseEntity<>(apiError, apiError.getStatus());

Now, let’s see how to deal with some exceptions that might be thrown when consuming our Spring Boot rest API.

Handle Resource Not Found Exception

As we have seen in the above example, Spring boot tends by default to return 500 error responses when ResourceNotFoundException is thrown.

500 status code is not meant to describe the situation where a requested resource (user in our case) is not found.

So, How can we fix that? The short answer lies in @ResponseStatus annotation.

First, we need to annotate our custom ResourceNotFoundException class with @ResponseStatus(HttpStatus.NOT_FOUND).

That way, we tell Spring Boot to return an HTTP response with NOT_FOUND status code when ResourceNotFoundException is raised.

        package com.restapi.msusers.exceptions;
        import org.springframework.http.HttpStatus;
        import org.springframework.web.bind.annotation.ResponseStatus;

        public class ResourceNotFoundException extends RuntimeException{
            private static final long serialVersionUID = 1L;

            public ResourceNotFoundException(String message) {

Now, we need to create a new exception handler method annotated in our global hander to deal with ResourceNotFoundException the proper way.

        public ResponseEntity<Object> handleResourceNotFoundException(
                ResourceNotFoundException ex) {
            List<String> details = new ArrayList<String>();
            ApiError err = new ApiError(
                "Resource Not Found" ,

test ResourceNotFoundException with postman

Handling HttpMessageNotReadableException

This exception will be triggered if the request body is invalid:

        protected ResponseEntity<Object> handleHttpMessageNotReadable(
                HttpMessageNotReadableException ex, 
                HttpHeaders headers, 
                HttpStatus status, 
                WebRequest request) {
            List<String> details = new ArrayList<String>();
            ApiError err = new ApiError(
                "Malformed JSON request" ,

test HttpMessageNotReadableException with postman

Handle MethodArgumentNotValidException

MethodArgumentNotValidException occurs when a handler method argument annotated with @Valid annotation failed validation.

        protected ResponseEntity<Object> handleMethodArgumentNotValid(
                MethodArgumentNotValidException ex,
                HttpHeaders headers, 
                HttpStatus status, 
                WebRequest request) {
            List<String> details = new ArrayList<String>();
            details = ex.getBindingResult()
                        .map(error -> error.getObjectName()+ " : " +error.getDefaultMessage())
            ApiError err = new ApiError(
                "Validation Errors" ,

test MethodArgumentNotValidException with postman

Dealing with MethodArgumentTypeMismatchException

The exception, as the name implies, is thrown when a method parameter has the wrong type:

        protected ResponseEntity<Object> handleMethodArgumentTypeMismatch(
            MethodArgumentTypeMismatchException ex,
            WebRequest request) {
            List<String> details = new ArrayList<String>();
            ApiError err = new ApiError(
                "Type Mismatch" ,

test MethodArgumentTypeMismatchException with postman

Handle ConstraintViolationException

ConstraintViolationException reports the result of constraint violations.

        public ResponseEntity<?> handleConstraintViolationException(
            Exception ex, 
            WebRequest request) {
            List<String> details = new ArrayList<String>();
            ApiError err = new ApiError(
                "Constraint Violations" ,

test ConstraintViolationException with postman

Handle MissingServletRequestParameterException

MissingServletRequestParameterException indicates that a controller method does not receive a required parameter:

        protected ResponseEntity<Object> handleMissingServletRequestParameter(
                MissingServletRequestParameterException ex, HttpHeaders headers,
                HttpStatus status, WebRequest request) {
            List<String> details = new ArrayList<String>();
            details.add(ex.getParameterName() + " parameter is missing");

            ApiError err = new ApiError(
                "Missing Parameters" ,

test MissingServletRequestParameterException with postman

Handling HttpMediaTypeNotSupportedException

The Exception informs that the specified request media type (Content type) is not supported.

        protected ResponseEntity<Object> handleHttpMediaTypeNotSupported(
                HttpMediaTypeNotSupportedException ex,
                HttpHeaders headers,
                HttpStatus status,
                WebRequest request) {
            List<String> details = new ArrayList<String>();
            StringBuilder builder = new StringBuilder();
            builder.append(" media type is not supported. Supported media types are ");
            ex.getSupportedMediaTypes().forEach(t -> builder.append(t).append(", "));

            ApiError err = new ApiError(
                "Unsupported Media Type" ,

test HttpMediaTypeNotSupportedException with postman

Handle NoHandlerFoundException

By default, DispatcherServlet sends a 404 response if there is no handler for a particular request.

So, to override the default behavior of our Servlet and throw NoHandlerFoundException instead, we need to add the following properties to the file.



Now, we can handle NoHandlerFoundException in the same way we did with other exceptions.

        protected ResponseEntity<Object> handleNoHandlerFoundException(
                NoHandlerFoundException ex, 
                HttpHeaders headers, 
                HttpStatus status, 
                WebRequest request) {

            List<String> details = new ArrayList<String>();
            details.add(String.format("Could not find the %s method for URL %s", ex.getHttpMethod(), ex.getRequestURL()));
            ApiError err = new ApiError(
                "Method Not Found" ,

test NoHandlerFoundException with postman

Deal with ALL Other Exceptions

Defining a global exception hander allows us to deal with all those exceptions that don’t have specific handlers.

        @ExceptionHandler({ Exception.class })
        public ResponseEntity<Object> handleAll(
            Exception ex, 
            WebRequest request) {
            List<String> details = new ArrayList<String>();
            ApiError err = new ApiError(
                "Error occurred" ,


Building a clean and proper exception handling is one of the main fundamental requirements that can make our API design more flexible and efficient.

You can find the full implementation of this tutorial in my Github repository:

Take care and stay safe.