Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

In this article, we’ll look at how to use HttpStatusCode in Spring Boot applications, focusing on the most recent enhancements introduced in version 3.3.3. With these enhancements, HttpStatusCode has been incorporated into the HttpStatus implementation, simplifying how we work with HTTP status codes.

The main purpose of these improvements is to provide a more flexible and reliable method for handling both standard and custom HTTP status codes, giving us higher flexibility and extensibility when working with HTTP responses while maintaining backward compatibility.

2. HttpStatus Enumerator

Prior to Spring 3.3.3, HTTP status codes were represented as enums in HttpStatus. This limited the use of custom or non-standard HTTP status codes as enums are a fixed set of predefined values.

Even though the HttpStatus class hasn’t been deprecated, some enums and methods that return raw integer status codes, such as getRawStatusCode() and rawStatusCode(), are now deprecated. Still, using the @ResponseStatus annotation to improve code readability remains the recommended approach.

We may also use HttpStatus in conjunction with HttpStatusCode for more flexible HTTP response management:

@GetMapping("/exception")
public ResponseEntity<String> resourceNotFound() {
    HttpStatus statusCode = HttpStatus.NOT_FOUND;
    if (statusCode.is4xxClientError()) {
        return new ResponseEntity<>("Resource not found", HttpStatusCode.valueOf(404));
    }
    return new ResponseEntity<>("Resource found", HttpStatusCode.valueOf(200));
}

3. HttpStatusCode Interface

The HttpStatusCode interface is designed to support custom status codes beyond the predefined ones in HttpStatus. It has 8 instance methods:

  • is1xxInformational()
  • is2xxSuccessful()
  • is3xxRedirection()
  • is4xxClientError()
  • is5xxServerError()
  • isError()
  • isSameCodeAs(HttpStatusCode other)
  • value()

These methods not only increase the flexibility of dealing with different HTTP statuses but also streamline the process of checking response categories, which improves the clarity and efficiency of status code management.

Let’s look at an example of how we may use them in practice:

@GetMapping("/resource")
public ResponseEntity successStatusCode() {
    HttpStatusCode statusCode = HttpStatusCode.valueOf(200);
    if (statusCode.is2xxSuccessful()) {
        return new ResponseEntity("Success", statusCode);
    }

    return new ResponseEntity("Moved Permanently", HttpStatusCode.valueOf(301));
}

3.1. Static Method valueOf(int)

This method returns an HttpStatusCode object for the given int value. The input parameter must be a 3-digit positive number, or else we get an IllegalArgumentException.

valueOf() maps a status code to a corresponding enum value within HttpStatus. If no existing entry matches the provided status code, the method defaults to returning an instance of DefaultHttpStatusCode.

The DefaultHttpStatusCode class implements the HttpStatusCode and offers a straightforward implementation of the value() method, which returns the original integer value used to initialize it. This approach ensures that all HTTP status codes, whether custom or non-standard, remain easy to work with:

@GetMapping("/custom-exception")
public ResponseEntity<String> goneStatusCode() {
    throw new ResourceGoneException("Resource Gone", HttpStatusCode.valueOf(410));
}

4. Using HttpStatusCode in Custom Exceptions

Next, let’s look at how to use a custom exception with HttpStatusCode within an ExceptionHandler. We’ll use the @ControllerAdvice annotation to handle exceptions globally across all controllers, and the @ExceptionHandler annotation to manage instances of the custom exception.

This approach centralizes error handling in Spring MVC applications, making the code cleaner and more maintainable.

4.1. @ControllerAdvice and @ExceptionHandler

@ControllerAdvice handles exceptions globally, while @ExceptionHandler manages custom exception instances to return consistent HTTP responses with the exception message and status code.

Let’s look at how we can use both annotations in practice:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(CustomException.class)
    public ResponseEntity<String> handleGoneException(CustomException e) {
        return new ResponseEntity<>(e.getMessage(), e.getStatusCode());
    }
}

4.2. Custom Exceptions

Next, let’s define a CustomException class that extends RuntimeException and includes an HttpStatusCode field, enabling custom messages and HTTP status codes for more precise error handling:

public class CustomException extends RuntimeException {

    private final HttpStatusCode statusCode;

    public CustomException(String message, HttpStatusCode statusCode) {
        super(message);
        this.statusCode = statusCode;
    }

    public HttpStatusCode getStatusCode() {
        return statusCode;
    }
}

5. Conclusion

The HttpStatus enum contains a limited set of standard HTTP status codes, which in older versions of Spring worked well for most use cases. However, they lacked flexibility in defining custom status codes.

Spring Boot 3.3.3 introduces HttpStatusCode, addressing this limitation by allowing us to define custom status codes. This provides a more flexible way to handle HTTP status codes, with instance methods for commonly used status codes such as is2xxSuccessful() and is3xxRedirection(), ultimately allowing for more granular control over response handling.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW