Simplifying HTTP Response Status Handling in SpringBoot with @ResponseStatus

In this tutorial, the author introduces the @ResponseStatus annotation in SpringBoot and demonstrates how it can eliminate repetitive manual status‑code handling, making API development cleaner and less error‑prone.

Why @ResponseStatus can handle all response status codes

Traditionally, developers manually set HTTP status codes using ResponseEntity , which leads to verbose code. The @ResponseStatus annotation allows automatic status‑code assignment for controller methods or exception classes, simplifying the process.

public ResponseEntity
handleNotFound() {
    return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
}

By annotating a method or exception with @ResponseStatus , Spring automatically sets the specified status code, removing the need for explicit ResponseEntity creation.

The magic of @ResponseStatus : automatic status setting

The annotation can be placed on a method or a custom exception class. When the method is invoked or the exception is thrown, Spring sets the HTTP response status to the value defined in the annotation.

Example for a 404 error:

@ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "Resource not found")
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

When ResourceNotFoundException is thrown, Spring returns a 404 response with the reason "Resource not found" without any additional code.

Advanced usage: custom exceptions and status codes

The annotation also works with custom exceptions, enabling fine‑grained error responses. For instance:

@ResponseStatus(value = HttpStatus.BAD_REQUEST, reason = "Invalid input data")
public class InvalidInputException extends RuntimeException {
    public InvalidInputException(String message) {
        super(message);
    }
}

Throwing InvalidInputException results in a 400 response with the custom reason.

Advantages of @ResponseStatus

Simplifies status‑code setting : The annotation automatically applies the status, removing boilerplate.

Improves development efficiency : One line of annotation replaces multiple lines of manual code.

Enhances maintainability : Centralized status management makes the codebase cleaner and easier to understand.

Flexible error handling : Combined with custom exceptions, it supports diverse error‑response scenarios.

Real‑world application

In a recent API project, the team replaced manual ResponseEntity usage with @ResponseStatus for all error cases, drastically reducing code size and improving readability.

Example for a user‑not‑found error:

@ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "User not found")
public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

Using this annotation eliminates the need to manually set the 404 status each time the exception is thrown.

Conclusion

The @ResponseStatus annotation is a powerful tool in SpringBoot that streamlines HTTP response status handling, reduces repetitive code, and boosts development productivity.