Clean • Professional
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.
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.
Using ProblemDetail gives you real-world advantages:
ErrorResponse DTOsProblemDetail 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.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.
@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 appProblemDetail.forStatus() → sets HTTP statussetTitle() & setDetail() → define error message{
"type":"about:blank",
"title":"User Not Found",
"status":404,
"detail":"User with given ID does not exist",
"timestamp":1672567890123
}
Why Use ProblemDetail?
Client Request
|
v
Controller throws Exception
|
v
@RestControllerAdvice catches exception
|
v
ProblemDetail object created
|
v
Standard JSON error response returned
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"
}
When request validation fails in a Spring Boot REST API (using @Valid or @Validated), Spring throws a MethodArgumentNotValidException.
@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
This follows the RFC 7807 standard, which is recommended for modern REST APIs.
{
"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?
| 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+. |
@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
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:
Avoid ProblemDetail When:
@RestControllerAdviceProblemDetail over custom DTOstitle short & human-readableProblemDetail is the modern, standardized, and recommended approach for handling errors in Spring Boot 3+ REST APIs.
It provides: