ProblemDetail (Modern Error Handling – Spring Boot 3+)

ProblemDetail is the modern and standardized way to handle errors in Spring Boot 3+ REST APIs.

It is based on RFC 7807 – Problem Details for HTTP APIs, an industry standard for error responses.

Spring Boot introduced ProblemDetail to replace inconsistent custom error responses and make APIs clean, consistent, and future-ready.

What is ProblemDetail?

ProblemDetail is a Spring-provided class that represents API errors in a standard JSON format.

In simple words:

ProblemDetail = a standard, clean, and professional error response for REST APIs

It avoids responses like:

{
"error":"Something went wrong"
}

And replaces them with structured, meaningful responses.

Why Use ProblemDetail in Spring Boot?

Using ProblemDetail gives you real-world advantages:

Follows RFC 7807 international standard
No need to create custom ErrorResponse DTOs
Built-in support in Spring Boot 3+
Cleaner and shorter exception handling code
Better frontend & client-side error handling
Professional, production-ready REST APIs

Standard Fields in ProblemDetail (RFC 7807)

ProblemDetail follows the RFC 7807 standard, which defines a common structure for REST API error responses. Each field has a specific purpose, making error responses easy to understand for both developers and clients. These fields help APIs return clear, meaningful, and consistent error information instead of random or confusing messages.

type helps identify the category of the error using a URI. By default, Spring uses about:blank, but you can customize it for specific error types.
title provides a short and human-readable summary of what went wrong, suitable for displaying in UI messages.
status represents the HTTP status code, helping clients understand whether the error is due to bad input, missing data, or a server issue.
detail gives a more detailed explanation of the error, useful for debugging and logging.
instance (optional) points to the request path or resource that caused the error.
Custom properties allow you to include extra information such as timestamps, error codes, or validation errors, making debugging and frontend handling easier.

Basic Example – Global Exception Handling with ProblemDetail

This example demonstrates how to use ProblemDetail with @RestControllerAdvice for global exception handling in a Spring Boot 3+ REST API.

Instead of custom DTOs or plain text, it returns a standard RFC 7807 JSON error response.

Global Exception Handler

@RestControllerAdvice
publicclassGlobalExceptionHandler {

@ExceptionHandler(UserNotFoundException.class)
public ProblemDetailhandleUserNotFound(UserNotFoundException ex) {

ProblemDetailproblem=
                ProblemDetail.forStatus(HttpStatus.NOT_FOUND);

        problem.setTitle("User Not Found");
        problem.setDetail(ex.getMessage());
        problem.setProperty("timestamp", System.currentTimeMillis());

return problem;
    }
}

What Happens Here,

@RestControllerAdvice → enables global exception handling
@ExceptionHandler → catches the exception anywhere in the app
ProblemDetail.forStatus() → sets HTTP status
setTitle() & setDetail() → define error message
Returns a clean, standardized JSON response

Example JSON Response

{
"type":"about:blank",
"title":"User Not Found",
"status":404,
"detail":"User with given ID does not exist",
"timestamp":1672567890123
}

Why Use ProblemDetail?

Clean and readable
Follows RFC 7807 standard
Client-friendly error format
Built-in support in Spring Boot 3+

Flow of ProblemDetail (Global Handling)

Client Request
      |
      v
Controller throws Exception
      |
      v
@RestControllerAdvice catches exception
      |
      v
ProblemDetail object created
      |
      v
Standard JSON error response returned

Adding Custom Fields in ProblemDetail

You can easily attach extra debugging or business data:

problem.setProperty("errorCode","USER_404");
problem.setProperty("path","/users/10");

Output:

{
"title":"User Not Found",
"status":404,
"errorCode":"USER_404",
"path":"/users/10"
}

Handling Validation Errors with ProblemDetail

When request validation fails in a Spring Boot REST API (using @Valid or @Validated), Spring throws a MethodArgumentNotValidException.

Validation Exception Handler

@ExceptionHandler(MethodArgumentNotValidException.class)
public ProblemDetailhandleValidationErrors(MethodArgumentNotValidException ex) {

ProblemDetailproblem=
            ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);

    problem.setTitle("Validation Failed");
    problem.setDetail("Invalid request data");

    List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(err -> err.getField() +": " + err.getDefaultMessage())
            .toList();

    problem.setProperty("errors", errors);

return problem;
}

What This Validation Handler Does

Catches all validation errors globally
Returns HTTP 400 (Bad Request)
Provides a clear error title and message
Collects field-level validation errors
Sends a structured, readable JSON response

This follows the RFC 7807 standard, which is recommended for modern REST APIs.

Validation Error JSON Response

{
"title":"Validation Failed",
"status":400,
"detail":"Invalid request data",
"errors":[
"name: Name is required",
"email: Email should be valid"
]
}

Why Use ProblemDetail for Validation Errors?

Standard and consistent error format
Easy for frontend teams to show form errors
No need for custom validation DTOs
Built-in support in Spring Boot 3+
Clean and professional API responses

ProblemDetail vs Custom ErrorResponse

Feature	Custom ErrorResponse	ProblemDetail
Error Handling Standard	No official standard. Structure depends on developer choice.	Fully follows RFC 7807, an industry-accepted standard for REST API error responses.
Spring Boot Support	Not built-in. You must create DTO classes manually.	Built-in support starting from Spring Boot 3+.
Boilerplate Code	High – requires DTO, constructors, getters, setters, and mapping logic.	Very low – Spring provides `ProblemDetail` out of the box.
Consistency Across APIs	Inconsistent if multiple developers follow different formats.	Guaranteed consistency across all APIs and teams.
Customization	Possible, but requires manual changes in DTOs.	Easy using `setProperty()` to add custom fields like `timestamp`, `errorCode`, `path`.
Readability for Clients	Medium – clients must understand custom formats.	High – frontend and API consumers easily understand the standard format.
API Documentation (Swagger / OpenAPI)	Manual documentation needed.	Better compatibility with API documentation tools.
Maintenance Effort	High – changes must be applied in multiple places.	Low – changes are centralized and simple.
Future-Ready	Limited – not aligned with modern standards.	Fully future-ready and recommended for new APIs.
Best Use Case	Legacy applications or Spring Boot 2.x projects.	Modern REST APIs using Spring Boot 3+.

ProblemDetail vs @ControllerAdvice

@ControllerAdvice and ProblemDetail are NOT alternatives. They are designed to work together in modern Spring Boot applications.

Feature	`@ControllerAdvice`	`ProblemDetail`
Purpose	Handles and catches exceptions globally	Formats the error response body
Role	Exception handling mechanism	Error response representation
Scope	Global (all controllers)	Only the response content
Spring Boot Version	Spring Boot 2+	Spring Boot 3+
Returns	`ResponseEntity`, object, or `ProblemDetail`	Standard RFC 7807 JSON
Customization	Decide which exception to handle	Decide how the error looks
Used Together	Yes	Yes (inside handler methods)
Alternative To Each Other?	No	No

How They Work Together (Flow)

Exception thrownin Controller
            ↓
@ControllerAdvice catches exception
            ↓
@ExceptionHandlermethodexecutes
            ↓
ProblemDetailcreatesstandarderrorresponse
            ↓
JSONresponsesenttoclient

When Should You Use ProblemDetail?

ProblemDetail is a modern, standardized way to handle REST API errors in Spring Boot 3+. It’s based on RFC 7807, which ensures a consistent JSON structure for error responses. Knowing when to use it helps you build clean, maintainable, and professional APIs.

Use ProblemDetail When:

You are using Spring Boot 3 or above
Building REST APIs that require JSON responses
Developing microservices with standardized error handling
Creating public-facing or production APIs where clients expect predictable responses
You want clean, consistent, and standard error responses without creating custom DTOs

Avoid ProblemDetail When:

You are using Spring Boot 2.x (no built-in support)
Working on legacy systems that already rely on fixed custom error formats
Your application is primarily an MVC app returning HTML pages instead of JSON

Best Practices

Always use @RestControllerAdvice
Prefer ProblemDetail over custom DTOs
Keep title short & human-readable
Use correct HTTP status codes
Add custom fields only when necessary
Combine with custom business exceptions

Conclusion

ProblemDetail is the modern, standardized, and recommended approach for handling errors in Spring Boot 3+ REST APIs.

It provides:

Clean and consistent JSON responses
Industry-standard error format (RFC 7807)
Less boilerplate code
Better frontend & client experience
Production-ready error handling