Using Spring @ResponseStatus to Set HTTP Status Code

Table of Contents

1. Introduction
2. On Controller Methods
3. With Error Handlers
4. Conclusion

1. Introduction

In Spring MVC, we have many ways to set the status code of an HTTP response.

In this short tutorial, we will see the most straightforward way: using the @ResponseStatus annotation.

2. On Controller Methods

When an endpoint returns successfully, Spring provides an HTTP 200 (OK) response.

If we want to specify the response status of a controller method, we can mark that method with @ResponseStatus. It has two interchangeable arguments for the desired response status: code, and value. For example, we can indicate that the server refuses to brew coffee because it is a teapot:

@ResponseStatus(HttpStatus.I_AM_A_TEAPOT)
void teaPot() {}

When we want to signal an error, we can provide an error message via the reason argument:

@ResponseStatus(HttpStatus.BAD_REQUEST, reason = "Some parameters are invalid")
void onIllegalArgumentException(IllegalArgumentException exception) {}

Note, that when we set reason, Spring calls HttpServletResponse.sendError(). Therefore, it will send an HTML error page to the client, which makes it a bad fit for REST endpoints.

Also note, that Spring only uses @ResponseStatus, when the marked method completes successfully (without throwing an Exception).

3. With Error Handlers

We have three ways to use @ResponseStatus to convert an Exception to an HTTP response status:

using @ExceptionHandler
using @ControllerAdvice
marking the Exception class

In order to use the first two solutions, we have to define an error handler method. You can read more about this topic in this article.

We can use @ResponseStatus with these error handler methods the same way we did with regular MVC methods in the previous section.

When we don’t need dynamic error responses, the most straightforward solution is the third one: marking the Exception class with @ResponseStatus:

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

When Spring catches this Exception, it uses the settings we provided in @ResponseStatus.

Note, that when we mark an Exception class with @ResponseStatus, Spring always calls HttpServletResponse.sendError(), whether we set reason or not.

Also note, that Spring uses the same configuration for subclasses, unless we mark them with @ResponseStatus, too.