What is @ResponseStatus Annotation in Spring Boot?

@ResponseStatus is an annotation in Spring Boot and Spring MVC used to define the HTTP response status code for a controller method or exception class.

It tells Spring Boot which HTTP status should be returned to the client when a request is processed successfully or when an exception occurs.

In simple words, @ResponseStatus helps developers customize the HTTP response status returned by Spring Boot APIs.

---

Why is @ResponseStatus Used?

In REST APIs and web applications, HTTP status codes are very important because they help clients understand whether a request was successful or failed.

Examples:

• 200 OK → Request successful
• 201 CREATED → Resource created successfully
• 400 BAD REQUEST → Invalid request
• 404 NOT FOUND → Resource not found
• 500 INTERNAL SERVER ERROR → Server error

By default, Spring Boot automatically returns some status codes. But sometimes developers need custom status handling.

That is where @ResponseStatus becomes useful.

---

Package of @ResponseStatus

import org.springframework.web.bind.annotation.ResponseStatus;

---

Basic Syntax of @ResponseStatus

@ResponseStatus(HttpStatus.STATUS_NAME)

---

Simple Example of @ResponseStatus

@RestController
public class UserController {

    @GetMapping("/success")
    @ResponseStatus(HttpStatus.OK)
    public String success() {

        return "Request Successful";
    }
}

---

Output

Response Body:

Request Successful

HTTP Status:

200 OK

---

How @ResponseStatus Works Internally

When a client sends a request:

1. Spring Boot receives the HTTP request
2. The controller method executes
3. @ResponseStatus sets the HTTP status code
4. Spring Boot sends response with specified status

---

Using @ResponseStatus with POST API

In REST APIs, POST requests usually return:

201 CREATED

This indicates that a new resource was successfully created.

Example

@RestController
@RequestMapping("/students")
public class StudentController {

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public String addStudent() {

        return "Student Added Successfully";
    }
}

---

Output

Response Body:

Student Added Successfully

HTTP Status:

201 CREATED

---

Using @ResponseStatus with DELETE API

DELETE APIs often return:

204 NO CONTENT

Example

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteStudent(@PathVariable int id) {

    System.out.println("Student Deleted");
}

---

Output

HTTP Status:

204 NO CONTENT

---

Using @ResponseStatus with Exceptions

One of the most powerful uses of @ResponseStatus is exception handling.

Developers can associate specific HTTP status codes with custom exceptions.

---

Example: Custom Exception

@ResponseStatus(HttpStatus.NOT_FOUND)
public class StudentNotFoundException extends RuntimeException {

    public StudentNotFoundException(String message) {
        super(message);
    }
}

---

Using Exception in Controller

@RestController
public class StudentController {

    @GetMapping("/student/{id}")
    public String getStudent(@PathVariable int id) {

        if(id != 101) {
            throw new StudentNotFoundException("Student Not Found");
        }

        return "Student Found";
    }
}

---

Output

Response Body:

{
   "timestamp": "2026-05-18T10:00:00",
   "status": 404,
   "error": "Not Found",
   "message": "Student Not Found"
}

HTTP Status:

404 NOT FOUND

---

Common HTTP Status Codes Used with @ResponseStatus

Status Code	Meaning
200 OK	Request successful
201 CREATED	Resource created successfully
204 NO CONTENT	Request successful without response body
400 BAD REQUEST	Invalid client request
401 UNAUTHORIZED	Authentication required
403 FORBIDDEN	Access denied
404 NOT FOUND	Requested resource not found
500 INTERNAL SERVER ERROR	Server-side error

---

Using reason Attribute in @ResponseStatus

Spring Boot allows custom reason messages using:

reason = "message"

---

Example

@ResponseStatus(
        value = HttpStatus.BAD_REQUEST,
        reason = "Invalid Student Request"
)
public class InvalidStudentException extends RuntimeException {
}

---

Difference Between @ResponseStatus and ResponseEntity

Feature	@ResponseStatus	ResponseEntity
Status Handling	Static	Dynamic
Headers Support	No	Yes
Response Body Control	Limited	Full Control
Best Use Case	Simple APIs	Advanced REST APIs

---

Example Using ResponseEntity

@GetMapping("/student")
public ResponseEntity<String> getStudent() {

    return new ResponseEntity<>(
            "Student Found",
            HttpStatus.OK
    );
}

---

Which One is Better?

For simple status handling, @ResponseStatus is sufficient.

For advanced API responses with headers, custom body structure, and dynamic status codes, ResponseEntity is preferred.

---

Real-Time Example in E-Commerce Application

Suppose an e-commerce application creates a new product successfully.

@PostMapping("/products")
@ResponseStatus(HttpStatus.CREATED)
public String addProduct() {

    return "Product Added Successfully";
}

---

Response

HTTP Status:

201 CREATED

Response Body:

Product Added Successfully

---

Advantages of @ResponseStatus

• Simple and easy to use
• Improves REST API readability
• Provides clear HTTP status handling
• Useful for exception handling
• Reduces boilerplate code
• Helps frontend applications understand API responses

---

Disadvantages of @ResponseStatus

• Static response status handling
• Limited flexibility compared to ResponseEntity
• Cannot easily customize response headers
• Not suitable for highly dynamic APIs

---

Best Practices for Using @ResponseStatus

• Use proper HTTP status codes
• Use 201 CREATED for POST APIs
• Use 204 NO CONTENT for DELETE APIs
• Use exception-specific status codes
• Avoid exposing sensitive error details
• Use ResponseEntity for advanced responses

---

Common Interview Questions on @ResponseStatus

What is @ResponseStatus in Spring Boot?

@ResponseStatus is used to define the HTTP response status code for controller methods or exceptions.

Can @ResponseStatus be used with exceptions?

Yes. It is commonly used with custom exception classes to return specific HTTP status codes.

What is the difference between @ResponseStatus and ResponseEntity?

@ResponseStatus provides static status handling, while ResponseEntity provides complete control over status, headers, and response body.

Which HTTP status is commonly used for POST requests?

201 CREATED is commonly used for successful resource creation.

Can @ResponseStatus customize error messages?

Yes. The reason attribute can define custom messages.

---

Commonly Used HTTP Status Categories

Category	Range	Description
Informational	100-199	Request received
Successful	200-299	Request successful
Redirection	300-399	Further action needed
Client Error	400-499	Client-side problem
Server Error	500-599	Server-side problem

---

Conclusion

@ResponseStatus is an important annotation in Spring Boot used to customize HTTP response status codes for REST APIs and exception handling.

It improves API readability, helps frontend applications understand server responses, and provides better RESTful API design.

It is widely used in enterprise applications, microservices, cloud-native APIs, and modern web applications.

Understanding @ResponseStatus is essential for Spring Boot developers because proper HTTP status handling is a critical part of REST API development and technical interviews.