Problem4J Spring

Designing clear and consistent error responses in a REST API is often harder than it looks. Without a shared standard, each application ends up inventing its own ad-hoc format, which quickly leads to inconsistency and confusion. RFC 7807 - Problem Details for HTTP APIs solves this by defining a simple, extensible JSON structure for error messages.

Problem4J brings this specification into the Spring ecosystem, offering a practical way to model, throw, and handle API errors using Problem objects. It helps you enforce a consistent error contract across your services, while staying flexible enough for custom exceptions and business-specific details.

Table of Contents

• Why bother with Problem4J
• Features
• Usage
• Configuration
• Problem4J Links

Why bother with Problem4J

Even though Spring provides ProblemDetail and ErrorResponseException for RFC 7807-compliant error responses, they are mutable, minimal, and often require manual population of fields. In contrast, Problem4J was created to:

• Provide a fully immutable, fluent Problem model with support for extensions.
• Support declarative exception mapping via @ProblemMapping or programmatic one via ProblemException.
• Automatically interpolate exception fields and context metadata (e.g., traceId) into responses.
• Offer consistent error responses across WebMVC and WebFlux, including validation and framework exceptions.
• Allow custom extensions without boilerplate, making structured errors easier to trace and consume.

In short, Problem4J is designed for developers who want robust, traceable, and fully configurable REST API errors, while keeping everything RFC 7807-compliant.

Features

This module provides Spring integration for problem4j-core. library that integrates the RFC Problem Details model with exception handling in Spring Boot.

• ✅ Automatic mapping of exceptions to responses with Problem objects compliant with RFC 7807.
• ✅ Mapping of exceptions extending ProblemException to responses with Problem objects.
• ✅ Mapping of exceptions annotated with @ProblemMapping to responses with Problem objects.
• ✅ Fallback mapping of Exception to Problem objects representing 500 Internal Server Error.
• ✅ Simple configuration thanks to Spring Boot autoconfiguration.

Usage

The library provides two ways to convert exceptions into RFC 7807-compliant Problem responses. You can either extend ProblemException or use @ProblemMapping annotation on your own exception if modifying inheritance tree is not an option for.

For more details and usage examples, see the submodule README.md files:

• problem4j-spring-web/README.md,
• problem4j-spring-webflux/README.md,
• problem4j-spring-webmvc/README.md.

Add library as dependency to Maven or Gradle. See the actual versions on Maven Central. Add it along with repository in your dependency manager. Java 17 or higher is required to use this library.

Tested with Spring Boot 3+, but mostly on 3.5.x. However, the idea for v1.x of this library was to be backwards compatible down to Spring Boot 3.0.0. Integration with Spring Boot 4 (once its released) will most likely be released as v2.x if v1.x won't be compatible.

1. Maven:

   <dependencies>
       <!-- pick the one for your project -->
       <dependency>
           <groupId>io.github.malczuuu.problem4j</groupId>
           <artifactId>problem4j-spring-webflux</artifactId>
           <version>1.0.0-alpha2</version>
       </dependency>
       <dependency>
           <groupId>io.github.malczuuu.problem4j</groupId>
           <artifactId>problem4j-spring-webmvc</artifactId>
           <version>1.0.0-alpha2</version>
       </dependency>
   </dependencies>

2. Gradle (Groovy or Kotlin DSL):

   dependencies {
       // pick the one for your project
       implementation("io.github.malczuuu.problem4j:problem4j-spring-webflux:1.0.0-alpha2")
       implementation("io.github.malczuuu.problem4j:problem4j-spring-webmvc:1.0.0-alpha2")
   }

Configuration

Library can be configured with following properties.

problem4j.detail-format

Property that specifies how exception handling imported with this module should print "detail" field of Problem model (lowercase, capitalized - default, uppercase). Useful for keeping the same style of errors coming from library and your application.

problem4j.tracing-header-name

Property that specifies the name of the HTTP header used for tracing requests. If set, the trace identifier from this header can be injected into the Problem response, for example into theinstance field when combined with problem4j.instance-override. Defaults to null (disabled).

problem4j.instance-override

Property that defines a template for overriding the instance field in Problem responses.The value may contain the special placeholder {traceId}, which will be replaced at runtime with the trace identifier from the current request ( see problem4j.tracing-header-name). Defaults to null (no override applied).

Problem4J Links

• problem4j-core - Core library defining Problem model and ProblemException.
• problem4j-jackson - Jackson module for serializing and deserializing Problem objects.
• problem4j-spring - Spring modules extending ResponseEntityExceptionHandler for handling exceptions and returning Problem responses.