RFC 7807 Problem Details and Consistent Error Responses

What Is RFC 7807?

RFC 7807 Fields

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User with id 42 does not exist.",
  "instance": "/api/users/42"
}

Spring 6 ProblemDetail

import org.springframework.http.ProblemDetail;

@ExceptionHandler(ResourceNotFoundException.class)
public ProblemDetail handleNotFound(ResourceNotFoundException ex, HttpServletRequest req) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    pd.setType(URI.create("https://api.example.com/errors/not-found"));
    pd.setTitle("Resource Not Found");
    pd.setInstance(URI.create(req.getRequestURI()));
    return pd;
}

Adding Custom Extensions

ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
pd.setTitle("Validation Failed");
pd.setProperty("errors", fieldErrors); // custom extension
pd.setProperty("timestamp", Instant.now());

Enabling RFC 7807 for Spring MVC

# application.properties:
spring.mvc.problemdetails.enabled=true

ErrorResponseException

throw new ErrorResponseException(HttpStatus.CONFLICT,
    ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
        "Email already exists: " + email), null);

Custom ProblemDetail Subclass

public class ValidationProblemDetail extends ProblemDetail {
    private final Map<String, String> fieldErrors;
    public ValidationProblemDetail(Map<String, String> errors) {
        super(HttpStatus.BAD_REQUEST.value());
        this.fieldErrors = errors;
        setTitle("Validation Failed");
        setProperty("fieldErrors", errors);
    }
}

Content Type: application/problem+json

return ResponseEntity.status(HttpStatus.NOT_FOUND)
    .contentType(MediaType.APPLICATION_PROBLEM_JSON)
    .body(pd);

Consistent Error Structure Checklist

Trace IDs for Observability

pd.setProperty("traceId", MDC.get("traceId"));
pd.setProperty("timestamp", Instant.now());

Testing Problem Details

mockMvc.perform(get("/api/users/999"))
    .andExpect(status().isNotFound())
    .andExpect(content().contentType("application/problem+json"))
    .andExpect(jsonPath("$.status").value(404))
    .andExpect(jsonPath("$.title").value("Resource Not Found"));

Quick Check

Recap