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