Spring Boot @ResponseStatus
last modified July 6, 2020
Spring Boot @ResponseStatus tutorial shows how to use @ResponseStatus annotation in a Spring application.
Spring is a popular Java application framework and Spring Boot is an evolution of Spring that helps create stand-alone, production-grade Spring based applications easily.
@ResponseStatus
@ResponseStatus
marks a method or exception class with the status
code and reason message that should be returned. The status code is applied to
the HTTP response when the handler method is invoked, or whenever the specified
exception is thrown. It overrides status information set by other means, like
ResponseEntity
or redirect:
.
Spring Boot @ResponseStatus example
In the following application, we demonstrate the usage of the @ResponseStatus
annotation. The application simulates a form for retrieving orders by their Id.
Trying to find orders with an Id greater than 500 will throw an exception. As a consequence
of this exception, a custom error page is displayed.
pom.xml src ├── main │ ├── java │ │ └── com │ │ └── zetcode │ │ ├── Application.java │ │ ├── controller │ │ │ └── MyController.java │ │ └── exception │ │ └── OrderNotFoundException.java │ └── resources │ ├── static │ │ └── index.html │ └── templates │ └── error.ftlh └── test └── java
This is the project structure of the Spring application.
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.zetcode</groupId> <artifactId>springbootresponsestatusex</artifactId> <version>1.0-SNAPSHOT</version> <packaging>jar</packaging> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.source>11</maven.compiler.source> <maven.compiler.target>11</maven.compiler.target> </properties> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.2.RELEASE</version> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-freemarker</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
This is the Maven pom.xml
file. The spring-boot-starter-freemarker
is a dependency for Freemarker template engine; the spring-boot-maven-plugin
packages Spring applications into executable JAR or WAR archives.
package com.zetcode.controller; import com.zetcode.exception.OrderNotFoundException; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.ResponseBody; @Controller public class MyController { @RequestMapping(value = "/orders/{id}") @ResponseBody public String getOrder(@PathVariable("id") long id) { if (id < 0 || id > 500) { var message = String.format("Order %d not found", id); throw new OrderNotFoundException(message); } var message = String.format("Returning order %d", id); return message; } }
The MyController's
getOrder()
method responds to
the client request. It reads the order Id from the path with @PathVariable
.
if (id < 0 || id > 500) { var message = String.format("Order %d not found", id); throw new OrderNotFoundException(message); }
For invalid orders (id < 0) and orders greater than 500, we throw the
OrderNotFoundException
exception. This is a simple simulation
of an order system.
var message = String.format("Returning order %d", id);
For other orders Ids, we return a message indicating that the order was found and returned.
package com.zetcode.exception; import org.springframework.http.HttpStatus; import org.springframework.web.bind.annotation.ResponseStatus; @ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "No such order") public class OrderNotFoundException extends RuntimeException { public OrderNotFoundException(String message) { super(message); } }
We have a custom OrderNotFoundException
. It is decorated with
the @ResponseStatus
annotation. The value is set to HttpStatus.NOT_FOUND
and the reason message says "No such order". This information will be used in the error page.
<!DOCTYPE html> <html> <head> <title>Home page</title> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <a href="/orders/505/">Get order with Id 505</a> </body> </html>
This is the home page. It contains a link that looks for an order with Id 505.
The file is located in the src/main/resources/static
directory.
<html> <head> <title>Error page</title> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <div> <h1>Error occurred</h1> <p>${status}: ${error} - ${message}</p> </div> </body> </html>
The error.ftlh
is a generic error page. It is Freemarker template file which shows
status, error, and the reason message. These values were set with @ResponseStatus
earlier. It is located in the src/main/resources/templates
directory.
package com.zetcode; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
Application
is the entry point which sets up Spring Boot
application.

In this tutorial, we have shown how to use the @ResponseStatus
annotation in a Spring application.