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:

Date Time trong Java 8
HashSet trong Java hoạt động như thế nào?
Java Program to Check Cycle in a Graph using Topological Sort
Java Program to Implement a Binary Search Algorithm for a Specific Search Sequence
Java Program to Apply DFS to Perform the Topological Sorting of a Directed Acyclic Graph
Concurrent Test Execution in Spring 5
Guide to Guava Multimap
Spring Security 5 for Reactive Applications
ClassNotFoundException vs NoClassDefFoundError
How to Read a Large File Efficiently with Java
Java Program to Convert a Decimal Number to Binary Number using Stacks
A Guide to the Java LinkedList
Spring Boot - Admin Client
Java Program to Implement Hash Tree
JPA/Hibernate Persistence Context
Java Program to Implement Triply Linked List
Spring Boot - Cloud Configuration Server
Implementing a Binary Tree in Java
Java Program to Check the Connectivity of Graph Using DFS
Java Program to Construct an Expression Tree for an Infix Expression
An Introduction to Java.util.Hashtable Class
Guide to Apache Commons CircularFifoQueue
Hướng dẫn Java Design Pattern – Dependency Injection
Why String is Immutable in Java?
Creating Docker Images with Spring Boot
Java Program to Generate a Random UnDirected Graph for a Given Number of Edges
Java Program to Search Number Using Divide and Conquer with the Aid of Fibonacci Numbers
Java Program to Implement the Checksum Method for Small String Messages and Detect
Hướng dẫn sử dụng luồng vào ra ký tự trong Java
Rest Web service: Filter và Interceptor với Jersey 2.x (P2)
Phương thức forEach() trong java 8
Java Program to Find Median of Elements where Elements are Stored in 2 Different Arrays