Spring Data JPA is a great way to handle the complexity of JPA with the powerful simplicity of Spring Boot .

Get started with Spring Data JPA through the guided reference course:

>> CHECK OUT THE COURSE

1. Overview

In this tutorial, we’ll discuss how to implement a global error handler for a Spring REST API.

We will use the semantics of each exception to build out meaningful error messages for the client, with the clear goal of giving that client all the info to easily diagnose the problem.

Further reading:

Learn how to apply status codes to HTTP responses in Spring with ResponseStatusException.

Read more → Exception Handling for a REST API - illustrate the new Spring recommended approach and earlier solutions.

2. A Custom Error Message

Let’s start by implementing a simple structure for sending errors over the wire — the ApiError :

public class ApiError {
    private HttpStatus status;
    private String message;
    private List<String> errors;
    public ApiError(HttpStatus status, String message, List<String> errors) {
        super();
        this.status = status;
        this.message = message;
        this.errors = errors;
    public ApiError(HttpStatus status, String message, String error) {
        super();
        this.status = status;
        this.message = message;
        errors = Arrays.asList(error);
The information here should be straightforward:
status – the HTTP status code
message – the error message associated with exception
error – List of constructed error messages
And of course, for the actual exception handling logic in Spring, we’ll use the @ControllerAdvice annotation:

@ControllerAdvice
public class CustomRestExceptionHandler extends ResponseEntityExceptionHandler {
3. Handle Bad Request Exceptions
3.1. Handling the Exceptions
Now let’s see how we can handle the most common client errors — basically scenarios of a client sending an invalid request to the API:
BindException – This exception is thrown when fatal binding errors occur.
MethodArgumentNotValidException – This exception is thrown when an argument annotated with @Valid failed validation:
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
  MethodArgumentNotValidException ex, 
  HttpHeaders headers, 
  HttpStatus status, 
  WebRequest request) {
    List<String> errors = new ArrayList<String>();
    for (FieldError error : ex.getBindingResult().getFieldErrors()) {
        errors.add(error.getField() + ": " + error.getDefaultMessage());
    for (ObjectError error : ex.getBindingResult().getGlobalErrors()) {
        errors.add(error.getObjectName() + ": " + error.getDefaultMessage());
    ApiError apiError = 
      new ApiError(HttpStatus.BAD_REQUEST, ex.getLocalizedMessage(), errors);
    return handleExceptionInternal(
      ex, apiError, headers, apiError.getStatus(), request);
Note that we are overriding a base method out of the ResponseEntityExceptionHandler and providing our own custom implementation.
That’s not always going to be the case. Sometimes, we’re going to need to handle a custom exception that doesn’t have a default implementation in the base class, as we’ll get to see later on here.
Next:
MissingServletRequestPartException – This exception is thrown when the part of a multipart request is not found.
MissingServletRequestParameterException – This exception is thrown when the request is missing a parameter:
@Override
protected ResponseEntity<Object> handleMissingServletRequestParameter(
  MissingServletRequestParameterException ex, HttpHeaders headers, 
  HttpStatus status, WebRequest request) {
    String error = ex.getParameterName() + " parameter is missing";
    ApiError apiError = 
      new ApiError(HttpStatus.BAD_REQUEST, ex.getLocalizedMessage(), error);
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
ConstraintViolationException – This exception reports the result of constraint violations:
@ExceptionHandler({ ConstraintViolationException.class })
public ResponseEntity<Object> handleConstraintViolation(
  ConstraintViolationException ex, WebRequest request) {
    List<String> errors = new ArrayList<String>();
    for (ConstraintViolation<?> violation : ex.getConstraintViolations()) {
        errors.add(violation.getRootBeanClass().getName() + " " + 
          violation.getPropertyPath() + ": " + violation.getMessage());
    ApiError apiError = 
      new ApiError(HttpStatus.BAD_REQUEST, ex.getLocalizedMessage(), errors);
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
TypeMismatchException – This exception is thrown when trying to set bean property with the wrong type.
MethodArgumentTypeMismatchException – This exception is thrown when method argument is not the expected type:
@ExceptionHandler({ MethodArgumentTypeMismatchException.class })
public ResponseEntity<Object> handleMethodArgumentTypeMismatch(
  MethodArgumentTypeMismatchException ex, WebRequest request) {
    String error = 
      ex.getName() + " should be of type " + ex.getRequiredType().getName();
    ApiError apiError = 
      new ApiError(HttpStatus.BAD_REQUEST, ex.getLocalizedMessage(), error);
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
3.2. Consuming the API From the Client
Let’s now have a look at a test that runs into a MethodArgumentTypeMismatchException.

We’ll send a request with id as String instead of long:
@Test
public void whenMethodArgumentMismatch_thenBadRequest() {
    Response response = givenAuth().get(URL_PREFIX + "/api/foos/ccc");
    ApiError error = response.as(ApiError.class);
    assertEquals(HttpStatus.BAD_REQUEST, error.getStatus());
    assertEquals(1, error.getErrors().size());
    assertTrue(error.getErrors().get(0).contains("should be of type"));
And finally, considering this same request:
Request method:	GET
Request path:	http://localhost:8080/spring-security-rest/api/foos/ccc
here’s what this kind of JSON error response will look like:
    "status": "BAD_REQUEST",
    "message": 
      "Failed to convert value of type [java.lang.String] 
       to required type [java.lang.Long]; nested exception 
       is java.lang.NumberFormatException: For input string: \"ccc\"",
    "errors": [
        "id should be of type java.lang.Long"
4. Handle NoHandlerFoundException
Next, we can customize our servlet to throw this exception instead of sending a 404 response:
<servlet>
    <servlet-name>api</servlet-name>
    <servlet-class>
      org.springframework.web.servlet.DispatcherServlet</servlet-class>        
    <init-param>
        <param-name>throwExceptionIfNoHandlerFound</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>
Then, once this happens, we can simply handle it just like any other exception:

@Override
protected ResponseEntity<Object> handleNoHandlerFoundException(
  NoHandlerFoundException ex, HttpHeaders headers, HttpStatus status, WebRequest request) {
    String error = "No handler found for " + ex.getHttpMethod() + " " + ex.getRequestURL();
    ApiError apiError = new ApiError(HttpStatus.NOT_FOUND, ex.getLocalizedMessage(), error);
    return new ResponseEntity<Object>(apiError, new HttpHeaders(), apiError.getStatus());
Here is a simple test:
@Test
public void whenNoHandlerForHttpRequest_thenNotFound() {
    Response response = givenAuth().delete(URL_PREFIX + "/api/xx");
    ApiError error = response.as(ApiError.class);
    assertEquals(HttpStatus.NOT_FOUND, error.getStatus());
    assertEquals(1, error.getErrors().size());
    assertTrue(error.getErrors().get(0).contains("No handler found"));
Let’s have a look at the full request:
Request method:	DELETE
Request path:	http://localhost:8080/spring-security-rest/api/xx
and the error JSON response:
    "status":"NOT_FOUND",
    "message":"No handler found for DELETE /spring-security-rest/api/xx",
    "errors":[
        "No handler found for DELETE /spring-security-rest/api/xx"
Next, we’ll look at another interesting exception.
5. Handle HttpRequestMethodNotSupportedException
The HttpRequestMethodNotSupportedException occurs when we send a requested with an unsupported HTTP method:
@Override
protected ResponseEntity<Object> handleHttpRequestMethodNotSupported(
  HttpRequestMethodNotSupportedException ex, 
  HttpHeaders headers, 
  HttpStatus status, 
  WebRequest request) {
    StringBuilder builder = new StringBuilder();
    builder.append(ex.getMethod());
    builder.append(
      " method is not supported for this request. Supported methods are ");
    ex.getSupportedHttpMethods().forEach(t -> builder.append(t + " "));
    ApiError apiError = new ApiError(HttpStatus.METHOD_NOT_ALLOWED, 
      ex.getLocalizedMessage(), builder.toString());
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
Here is a simple test reproducing this exception:
@Test
public void whenHttpRequestMethodNotSupported_thenMethodNotAllowed() {
    Response response = givenAuth().delete(URL_PREFIX + "/api/foos/1");
    ApiError error = response.as(ApiError.class);
    assertEquals(HttpStatus.METHOD_NOT_ALLOWED, error.getStatus());
    assertEquals(1, error.getErrors().size());
    assertTrue(error.getErrors().get(0).contains("Supported methods are"));
And here’s the full request:
Request method:	DELETE
Request path:	http://localhost:8080/spring-security-rest/api/foos/1
and the error JSON response:

    "status":"METHOD_NOT_ALLOWED",
    "message":"Request method 'DELETE' not supported",
    "errors":[
        "DELETE method is not supported for this request. Supported methods are GET "
6. Handle HttpMediaTypeNotSupportedException
Now let’s handle HttpMediaTypeNotSupportedException, which occurs when the client sends a request with unsupported media type:
@Override
protected ResponseEntity<Object> handleHttpMediaTypeNotSupported(
  HttpMediaTypeNotSupportedException ex, 
  HttpHeaders headers, 
  HttpStatus status, 
  WebRequest request) {
    StringBuilder builder = new StringBuilder();
    builder.append(ex.getContentType());
    builder.append(" media type is not supported. Supported media types are ");
    ex.getSupportedMediaTypes().forEach(t -> builder.append(t + ", "));
    ApiError apiError = new ApiError(HttpStatus.UNSUPPORTED_MEDIA_TYPE, 
      ex.getLocalizedMessage(), builder.substring(0, builder.length() - 2));
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
Here is a simple test running into this issue:
@Test
public void whenSendInvalidHttpMediaType_thenUnsupportedMediaType() {
    Response response = givenAuth().body("").post(URL_PREFIX + "/api/foos");
    ApiError error = response.as(ApiError.class);
    assertEquals(HttpStatus.UNSUPPORTED_MEDIA_TYPE, error.getStatus());
    assertEquals(1, error.getErrors().size());
    assertTrue(error.getErrors().get(0).contains("media type is not supported"));
Finally, here’s a sample request:
Request method:	POST
Request path:	http://localhost:8080/spring-security-
Headers:	Content-Type=text/plain; charset=ISO-8859-1
and the error JSON response:
    "status":"UNSUPPORTED_MEDIA_TYPE",
    "message":"Content type 'text/plain;charset=ISO-8859-1' not supported",
    "errors":["text/plain;charset=ISO-8859-1 media type is not supported. 
       Supported media types are text/xml 
       application/x-www-form-urlencoded 
       application/*+xml 
       application/json;charset=UTF-8 
       application/*+json;charset=UTF-8 */"
7. Default Handler
Lastly, we’re going to implement a fallback handler — a catch-all type of logic that deals with all other exceptions that don’t have specific handlers:
@ExceptionHandler({ Exception.class })
public ResponseEntity<Object> handleAll(Exception ex, WebRequest request) {
    ApiError apiError = new ApiError(
      HttpStatus.INTERNAL_SERVER_ERROR, ex.getLocalizedMessage(), "error occurred");
    return new ResponseEntity<Object>(
      apiError, new HttpHeaders(), apiError.getStatus());
8. Conclusion
Building a proper, mature error handler for a Spring REST API is tough and definitely an iterative process. Hopefully, this tutorial will be a good starting point as well as a good anchor for helping API clients to quickly and easily diagnose errors and move past them.
The full implementation of this tutorial can be found in the GitHub project. This is an Eclipse-based project, so it should be easy to import and run as it is.
Baeldung Pro – NPI EA (cat = Baeldung)


Baeldung Pro comes with both absolutely No-Ads as well as
finally with Dark Mode, for a clean learning experience:
>> Explore a clean
Baeldung
Once the early-adopter seats are all used, the price will go
up and stay at $33/year.





    
eBook – Java Concurrency – NPI EA (cat=Java Concurrency)


Handling concurrency in an application can be a tricky process
with many potential pitfalls. A solid grasp of the
fundamentals will go a long way to help minimize these issues.
Get started with understanding multi-threaded applications with
our Java Concurrency guide:
>> Download
the eBook
Partner – Orkes – NPI EA (tag = Microservices)


Modern software architecture is often broken. Slow delivery
leads to missed opportunities, innovation is stalled due to
architectural complexities, and engineering resources are
exceedingly expensive.
Orkes is the leading workflow orchestration platform
built to enable teams to transform the way they develop, connect,
and deploy applications, microservices, AI agents, and more.
With Orkes Conductor managed through Orkes Cloud, developers can
focus on building mission critical applications without worrying
about infrastructure maintenance to meet goals and, simply put,
taking new products live faster and reducing total cost of
ownership.
Try a 14-Day
Free Trial of Orkes Conductor today.
Partner – Microsoft – NPI EA (cat = Spring Boot)


Azure Container Apps is a fully managed serverless container
service that enables you to build and deploy modern,
cloud-native Java applications and microservices at scale. It
offers a simplified developer experience while providing the
flexibility and portability of containers.
Of course, Azure Container Apps has really solid support for our
ecosystem, from a number of build options, managed Java components,
native metrics, dynamic logger, and quite a bit more.
To learn more about Java features on Azure Container Apps, visit
the documentation
page.
You can also ask questions and leave feedback on the Azure
Container Apps GitHub page.
Partner – Jmix-Haulmont – NPI EA (cat= Spring Boot)


Whether you're just starting out or have years of experience,
Spring Boot is obviously a great choice for building a web
application.
Jmix builds on this highly powerful and mature Boot stack,
allowing devs to build and deliver full-stack web
applications without having to code the frontend. Quite
flexibly as well, from simple web GUI CRUD applications to complex
enterprise solutions.
Concretely, The Jmix Platform includes a framework built
on top of Spring Boot, JPA, and Vaadin, and comes with Jmix
Studio, an IntelliJ IDEA plugin equipped with a suite of
developer productivity tools.
The platform comes with interconnected out-of-the-box
add-ons for report generation, BPM, maps, instant web app
generation from a DB, and quite a bit more:
>> Become an efficient
full-stack developer with Jmix
Partner – Machinet – NPI EA (cat = Baeldung)


The AI Assistant to boost Boost your productivity writing unit
tests - Machinet AI.
AI is all the rage these days, but for very good reason. The
highly practical coding companion, you'll get the power of
AI-assisted coding and automated unit test generation.

Machinet's Unit Test AI Agent utilizes your own project
context to create meaningful unit tests that intelligently aligns
with the behavior of the code.

And, the AI Chat crafts code and fixes errors with ease,
like a helpful sidekick.

Simplify Your Coding Journey with Machinet AI:
Install Machinet AI in your IntelliJ

Partner – Codium – NPI EA (cat = Testing)


Explore the secure, reliable, and high-performance Test
Execution Cloud built for scale. Right in your IDE:
CodiumAI. Meaningful Code Tests for Busy Devs

Basically, write code that works the way you meant it to.
Partner – Machinet – NPI EA (cat = Testing)


AI is all the rage these days, but for very good reason. The
highly practical coding companion, you'll get the power of
AI-assisted coding and automated unit test generation.

Machinet's Unit Test AI Agent utilizes your own project
context to create meaningful unit tests that intelligently aligns
with the behavior of the code.

Simplify Your Coding Journey with Machinet AI:
Install Machinet AI in your IntelliJ

eBook – Java Streams – NPI EA (cat=Java Streams)


Since its introduction in Java 8, the Stream API has become a
staple of Java development. The basic operations like iterating,
filtering, mapping sequences of elements are deceptively simple to
But these can also be overused and fall into some common
pitfalls.
To get a better understanding on how Streams work and how
to combine them with other language features, check out our guide
to Java Streams:
>>Download the
E-book
eBook – HTTP Client – NPI EA (cat=HTTP Client-Side)


The Apache HTTP Client is a very robust library, suitable
for both simple and advanced use cases when testing HTTP
endpoints. Check out our guide covering basic request and
response handling, as well as security, cookies, timeouts, and
more:
>> Download the
eBook
Course – LS – NPI EA (cat=REST)


Get started with Spring Boot and with core Spring,
through the Learn Spring course:
>> CHECK OUT THE
COURSE
Course – LS – NPI – (cat=Spring)


Get started with Spring Boot and with core Spring,
through the Learn Spring course:
>> CHECK OUT THE
COURSE
Course – LS – NPI (cat=REST)


Get started with Spring Boot and with core Spring,
through the Learn Spring course:
>> CHECK OUT
THE COURSE
the E-book
Course – RWSB – NPI EA (cat=REST)

eBook – Guide Spring Cloud – NPI EA (cat=Cloud/Spring Cloud)

Download the E-book
eBook – Jackson – NPI EA – 2 (cat=Jackson)

Do JSON right with Jackson
Download the E-book
eBook – RwS Java – NPI EA (cat=Java)

Building a REST API with Spring 5?
Download the E-book
eBook – Maven – NPI EA (cat= Maven)

Get Started with Apache Maven
Download the E-book
eBook- Spring Reactive Guide – NPI EA (cat=Reactive)

Spring Reactive Guide
Download the E-book
eBook – Mockito – NPI EA (tag=Mockito)

Starting to test with Mockito?
Download the Guide
eBook – Persistence – NPI EA (cat=Persistence)

Download
the E-book
eBook – RwS – NPI (cat=REST/Spring MVC)

Building a REST API with Spring?
Download the E-book