Returning Custom Status Codes from Spring Controllers

1. Overview

This quick article will demonstrate a few ways to return custom HTTP status codes from Spring MVC controllers.

This is often important in order to more clearly express the result of a request to a client and using the full rich semantics of the HTTP protocol. For example, if something goes wrong with a request, sending a specific error code for each type of possible problem would allow the client to display an appropriate error message to the user.

The setup of a basic Spring MVC project is outside the scope of this article, but you can find more information here.

2. Returning Custom Status Codes

Spring provides a few primary ways to return custom status codes from its Controller classes:

  • using a ResponseEntity
  • using the @ResponseStatus annotation on exception classes, and
  • using the @ControllerAdvice and @ExceptionHandler annotations.

These options are not mutually exclusive; far from it, they can actually complement one another.

This article will cover the first two ways (ResponseEntity and @ResponseStatus). If you would like to learn more about using @ControllerAdvice and @ExceptionHandler, you can read about it here.

2.1. Returning Status Codes via a ResponseEntity

In a standard Spring MVC controller, we will define a simple mapping:

@RequestMapping(value = "/controller", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity sendViaResponseEntity() {
    return new ResponseEntity(HttpStatus.NOT_ACCEPTABLE);
}

Upon receiving a GET request to “/controller“, Spring will return a response with the 406 Code (Not Acceptable). We arbitrarily selected the specific response code for this example. You can return any HTTP status code (the full list can be found here).

2.2. Returning Status Codes via an Exception

We will add a second method to the controller to demonstrate how to use an Exception to return a status code:

@RequestMapping(value = "/exception", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity sendViaException() {
    throw new ForbiddenException();
}

Upon receiving a GET request to “/exception“, Spring will throw a ForbiddenException. This is a custom exception that we will define in a separate class:

@ResponseStatus(HttpStatus.FORBIDDEN)
public class ForbiddenException extends RuntimeException {}

No code is required in this exception. All the work is done by the @ResponseStatus annotation.

In this case, when the exception is thrown, the controller that threw it returns a response with the response code 403 (Forbidden). If necessary, you can also add a message in the annotation that will be returned along with the response.

In this case, the class would look like this:

@ResponseStatus(value = HttpStatus.FORBIDDEN, reason="To show an example of a custom message")
public class ForbiddenException extends RuntimeException {}

It is important to note that while it is technically possible to make an exception return any status code, in most cases it only makes logical sense to use exceptions for error codes (4XX and 5XX).

3. Conclusion

The tutorial showed how to return custom status codes from Spring MVC controllers.

The implementation can be found in the example GitHub project.

Related posts:

Java Program to Implement Caesar Cypher
Java Program to Find MST (Minimum Spanning Tree) using Kruskal’s Algorithm
Netflix Archaius with Various Database Configurations
Java Collections Interview Questions
Guide to the Java Queue Interface
Java Stream Filter with Lambda Expression
Hướng dẫn Java Design Pattern – Mediator
Multi Dimensional ArrayList in Java
Custom Cascading in Spring Data MongoDB
Java – Try with Resources
Java Program to Check if it is a Sparse Matrix
Inheritance and Composition (Is-a vs Has-a relationship) in Java
Java Program to Perform String Matching Using String Library
Java Program to Implement the Schonhage-Strassen Algorithm for Multiplication of Two Numbers
Loại bỏ các phần tử trùng trong một ArrayList như thế nào trong Java 8?
Java Program to Implement Regular Falsi Algorithm
Java Program to Implement Sparse Matrix
JUnit5 @RunWith
Java Program to Perform Encoding of a Message Using Matrix Multiplication
How to Find an Element in a List with Java
Các kiểu dữ liệu trong java
Guide to the Java Clock Class
Sử dụng CountDownLatch trong Java
Java Program to Implement Adjacency List
Hướng dẫn Java Design Pattern – Observer
Java Program to Construct K-D Tree for 2 Dimensional Data
How to Round a Number to N Decimal Places in Java
Java Program to Perform Addition Operation Using Bitwise Operators
Java Program to Implement Affine Cipher
Java Program to Implement CopyOnWriteArraySet API
Java Program to Implement First Fit Decreasing for 1-D Objects and M Bins
Deploy a Spring Boot WAR into a Tomcat Server