Spring Boot @ResponseStatus

last modified July 16, 2023

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 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.

├── main
│  ├── java
│  │  └── com
│  │      └── zetcode
│  │          ├── Application.java
│  │          ├── controller
│  │          │  └── MyController.java
│  │          └── exception
│  │              └── OrderNotFoundException.java
│  └── resources
│      ├── static
│      │  └── index.html
│      └── templates
│          └── error.ftlh
└── test
    ├── java
    └── resources

This is the project structure of the Spring application.

plugins {
    id 'org.springframework.boot' version '3.1.1'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-freemarker'

This is the Gradle build file. The spring-boot-starter-freemarker is a dependency for Freemarker template engine.

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;

public class MyController {

    @RequestMapping(value = "/orders/{id}")
    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) {


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>
        <title>Home page</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <a href="/orders/505/">Get order with Id 505</a>

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.

        <title>Error page</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

            <h1>Error occurred</h1>

            <p>${status}: ${error}</p>

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;

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 article we have shown how to use the @ResponseStatus annotation in a Spring application.


My name is Jan Bodnar and I am a passionate programmer with many years of programming experience. I have been writing programming articles since 2007. So far, I have written over 1400 articles and 8 e-books. I have over eight years of experience in teaching programming.

List all Spring Boot tutorials.