Problem to solve

When building REST APIs with Spring Boot, applications repeatedly implement the same set of HTTP semantic exceptions such as:

  • NotFound
  • Conflict
  • BadRequest
  • Forbidden
  • Unauthorized

Although Spring provides excellent low-level building blocks (ResponseStatusException, @ResponseStatus, @ControllerAdvice, and more recently ProblemDetail), there is no standard, reusable set of HTTP-oriented exceptions that applications can use out of the box.

As a result:

  • Almost every Spring Boot REST application defines its own versions of these exceptions
  • Boilerplate code is duplicated across projects
  • APIs become inconsistent in error semantics and structure
  • Teams repeatedly reinvent the same conventions

This is especially noticeable in applications that expose purely REST/HTTP APIs where these exceptions are infrastructure-level concerns rather than domain-specific ones.

Current workarounds

Typical approaches today include:

  • Defining custom exceptions annotated with @ResponseStatus
  • Throwing ResponseStatusException directly from application code
  • Mapping domain exceptions to HTTP responses using @ControllerAdvice

While these approaches are flexible, they still require every application to define and maintain the same basic HTTP semantics.

Proposed enhancement

Provide a standard set of HTTP semantic exceptions as part of Spring Boot (or a Spring Boot–provided module), for example:

  • NotFoundException
  • ConflictException
  • BadRequestException
  • UnauthorizedException
  • ForbiddenException

Key characteristics:

  • Focused purely on HTTP semantics (not domain-specific)
  • Designed for REST APIs
  • Minimal and opinionated, following Spring Boot conventions
  • Optional to use (no breaking changes)

Prior art

Other frameworks provide similar abstractions out of the box, for example:

  • NestJS (NotFoundException, ConflictException, etc.)
  • ASP.NET Web API (HTTP-specific exceptions and results)

Summary

This proposal is not about replacing existing mechanisms, but about offering a convention-based, reusable set of HTTP exceptions that most Spring Boot REST applications already need.

Comment From: bclozel

Good news, Spring Framework already ships exceptions extending ResponseStatusException. But by design, those are not meant to model an HTTP status by itself, but an actual problem happening in the application like UnsupportedMediaTypeStatusException and InvalidApiVersionException (bad request).

Your application should ship its own "business exceptions" and you can optionally make them extend ResponseStatusException or turn those business exceptions into HTTP exceptions with the Spring error handling (very often, you don't want to tie those exceptions to the web layer).

I think this is more a design principle: Spring will drive HTTP response statuses in various ways, but exceptions should not be the main mechanism.

Thanks for the suggestion but I'm declining this because this choice is by design.