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

ProblemDetail vs @ControllerAdvice

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

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