Respuestas Problem Detail según RFC 7807
Estandarice payloads de error legibles por máquinas mediante ProblemDetail de Spring y la compatibilidad con ErrorResponse.
Respuestas Problem Detail según RFC 7807 es una lección gratuita de Spring Boot 4 Complete Guide en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Spring Boot 4 Complete Guide, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Spring Boot 4 Complete Guide incluye 4 lecciones en total.
Partes de esta lección aún no han sido traducidas y se muestran en inglés.
Why Standardize Error Responses?
When an API fails, clients need a predictable, machine-readable error body. Hand-rolled JSON like {"error": "bad"} varies per endpoint and breaks integrations.
RFC 7807 ("Problem Details for HTTP APIs") defines a single, standard shape for error payloads. Spring Boot has first-class support for it through the ProblemDetail class and the ErrorResponse contract.
- Consistent across every endpoint
- Self-documenting via a
typeURI - Extensible with custom properties
The RFC 7807 Media Type and Fields
A Problem Detail response uses the media type application/problem+json and contains these standard members:
- type — a URI identifying the problem category (defaults to
about:blank) - title — a short, human-readable summary
- status — the HTTP status code (e.g. 404)
- detail — a human-readable explanation specific to this occurrence
- instance — a URI identifying the specific occurrence (often the request path)
You may also add custom extension members like errorCode or timestamp.
A Sample Problem+JSON Body
Here is what a client actually receives. Note the application/problem+json content type and the standard fields, plus an extension member errorCode.
{
"type": "https://api.shop.com/problems/out-of-stock",
"title": "Out of Stock",
"status": 409,
"detail": "Product 42 has only 3 units left, but 5 were requested.",
"instance": "/api/orders",
"errorCode": "INVENTORY_SHORTAGE"
}Building a ProblemDetail Programmatically
Spring's ProblemDetail is a simple value object. Use the static factory forStatus() or forStatusAndDetail(), then enrich it with setters.
You can attach custom members via setProperty(name, value). This object serializes directly to application/problem+json.
ProblemDetail problem = ProblemDetail.forStatusAndDetail(
HttpStatus.NOT_FOUND,
"Product 42 was not found");
problem.setTitle("Product Not Found");
problem.setType(URI.create("https://api.shop.com/problems/not-found"));
problem.setInstance(URI.create("/api/products/42"));
problem.setProperty("errorCode", "PRODUCT_NOT_FOUND");Returning ProblemDetail from a Controller
A controller method can return a ProblemDetail directly, or wrap it in a ResponseEntity for full control of headers. Spring sets the status from the ProblemDetail and serializes the body as problem+json.
@GetMapping("/products/{id}")
public ResponseEntity<ProblemDetail> getProduct(@PathVariable Long id) {
return productRepo.findById(id)
.map(p -> ResponseEntity.ok().<ProblemDetail>build())
.orElseGet(() -> {
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
HttpStatus.NOT_FOUND, "No product with id " + id);
pd.setTitle("Product Not Found");
return ResponseEntity.status(404).body(pd);
});
}The ErrorResponse Contract
Returning ProblemDetail manually works, but Spring prefers exceptions to carry their own problem detail. The ErrorResponse interface couples an HTTP status, headers, and a ProblemDetail body.
Spring MVC automatically renders any thrown exception that implements ErrorResponse as problem+json. The convenience class ErrorResponseException is a ready-made implementation you can throw directly.
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
HttpStatus.CONFLICT, "Email already registered");
pd.setTitle("Duplicate Email");
pd.setProperty("errorCode", "DUPLICATE_EMAIL");
throw new ErrorResponseException(HttpStatus.CONFLICT, pd, null);Custom Exceptions Implementing ErrorResponse
For domain errors, implement ErrorResponse on your own exception. By extending ErrorResponseException, you inherit status, headers, and body handling, and just supply a configured ProblemDetail.
This keeps error definitions next to the domain logic and out of controllers.
public class OutOfStockException extends ErrorResponseException {
public OutOfStockException(long productId, int available, int requested) {
super(HttpStatus.CONFLICT, asProblemDetail(productId, available, requested), null);
}
private static ProblemDetail asProblemDetail(long id, int avail, int req) {
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
HttpStatus.CONFLICT,
"Product " + id + " has only " + avail + " left, but " + req + " requested.");
pd.setType(URI.create("https://api.shop.com/problems/out-of-stock"));
pd.setTitle("Out of Stock");
pd.setProperty("errorCode", "INVENTORY_SHORTAGE");
return pd;
}
}Centralizing with @ControllerAdvice
The cleanest pattern: throw plain domain exceptions, then convert them to ProblemDetail in one place using @RestControllerAdvice and @ExceptionHandler.
The handler returns a ProblemDetail; Spring applies the status and problem+json content type automatically.
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ProductNotFoundException.class)
public ProblemDetail handleNotFound(ProductNotFoundException ex) {
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
HttpStatus.NOT_FOUND, ex.getMessage());
pd.setTitle("Product Not Found");
pd.setType(URI.create("https://api.shop.com/problems/not-found"));
pd.setProperty("errorCode", "PRODUCT_NOT_FOUND");
return pd;
}
}Extending ResponseEntityExceptionHandler
Spring's built-in exceptions (validation failures, unreadable bodies, missing parameters) are handled by ResponseEntityExceptionHandler. Since Spring Boot 3, these already produce ProblemDetail bodies.
Extend it in your advice to override or enrich the defaults while keeping framework error handling consistent.
@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
ProblemDetail pd = ex.getBody();
pd.setTitle("Validation Failed");
pd.setProperty("errorCode", "VALIDATION_ERROR");
return handleExceptionInternal(ex, pd, headers, status, request);
}
}Adding Standard Extension Properties
Common extensions include a timestamp and a traceId for log correlation. Add them in one place so every error carries them.
Use setProperty with serializable values; Instant serializes to an ISO-8601 string by default.
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
HttpStatus.BAD_REQUEST, "Quantity must be positive");
pd.setTitle("Invalid Quantity");
pd.setProperty("timestamp", Instant.now());
pd.setProperty("traceId", MDC.get("traceId"));
pd.setProperty("errorCode", "INVALID_QUANTITY");Configuring Defaults in application.yml
Spring can include extra context automatically. Enabling these properties makes the framework attach standard details without code changes.
spring.mvc.problemdetails.enabled=trueturns on problem+json for built-in exceptions (default in Boot 3+)server.error.include-messageandinclude-binding-errorscontrol how much detail is exposed
Keep sensitive details out of production responses by tuning these flags.
spring:
mvc:
problemdetails:
enabled: true
server:
error:
include-message: on_param
include-binding-errors: on_param
include-stacktrace: neverQuick Check: Choosing the Right Pattern
You have several domain exceptions (not-found, conflict, forbidden) and want every error across all controllers to emit consistent application/problem+json with shared extensions like traceId. What is the recommended Spring approach?
Recap: RFC 7807 in Spring Boot
You learned how to standardize error payloads with RFC 7807:
- ProblemDetail is the value object for
application/problem+json, withtype,title,status,detail,instanceplus custom properties. - ErrorResponse / ErrorResponseException let exceptions carry their own problem detail.
- @RestControllerAdvice centralizes conversion of domain exceptions into ProblemDetail.
- ResponseEntityExceptionHandler already renders Spring's built-in exceptions as problem+json, and can be extended.
- Add extensions like
errorCode,timestamp, andtraceId, and tune exposure viaapplication.yml.
The result: a single, predictable, machine-readable error contract across your whole API.
Aprende Java con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 21
- Lecciones
- 84
Preguntas frecuentes
¿La lección «Respuestas Problem Detail según RFC 7807» es gratis?
Sí — el texto completo de «Respuestas Problem Detail según RFC 7807» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Spring Boot 4 Complete Guide, actualiza a CoddyKit PRO. El curso de Spring Boot 4 Complete Guide incluye 4 lecciones en total.
¿Qué aprenderé en «Respuestas Problem Detail según RFC 7807»?
Estandarice payloads de error legibles por máquinas mediante ProblemDetail de Spring y la compatibilidad con ErrorResponse. Practicas Spring Boot 4 Complete Guide con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Spring Boot 4 Complete Guide?
No se requiere experiencia previa. Spring Boot 4 Complete Guide en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Respuestas Problem Detail según RFC 7807»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Spring Boot 4 Complete Guide?
Sí. Cada lección de Spring Boot 4 Complete Guide incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Restricciones de Bean Validation y grupos de restricciones
- Creación de anotaciones de restricciones personalizadas
- Gestión global de excepciones con @ControllerAdvice
- Respuestas Problem Detail según RFC 7807