RFC 7807 Problem Details in Spring Boot: Standardized API Error Responses

``java @ExceptionHandler(DataIntegrityViolationException.class) public ProblemDetail handleConstraintViolation(DataIntegrityViolationException ex, WebRequest request) { ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.CONFLICT); pd.setTitle("Resource Conflict"); pd.setDetail("Duplicate entry detected"); pd.setType(URI.create("https://api.example.com/errors/conflict")); pd.setInstance(URI.create(request.getDescription(false).replace("uri=", ""))); log.warn("Conflict: {}", ex.getMessage()); return pd; } ``

Output: ``json {"type":"https://api.example.com/errors/conflict","title":"Resource Conflict","status":409,"detail":"Duplicate entry detected","instance":"/api/orders/123"} ``

@ExceptionHandler(DataIntegrityViolationException.class)
public ProblemDetail handleConstraintViolation(DataIntegrityViolationException ex,
                                                WebRequest request) {
    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.CONFLICT);
    pd.setTitle("Resource Conflict");
    pd.setDetail("Duplicate entry detected");
    pd.setType(URI.create("https://api.example.com/errors/conflict"));
    pd.setInstance(URI.create(request.getDescription(false).replace("uri=", "")));
    log.warn("Conflict: {}", ex.getMessage());
    return pd;
}

Customizing Problem Details with Extensions

The RFC allows custom extension members — keys prefixed with x- (though Spring doesn't enforce this). In payment processing, you often need fields like "balance", "retry_after", or "error_code". Spring's ProblemDetail supports arbitrary properties via setProperty(). But beware: extension keys should be documented in your type URI. Never use detail for structured data like a list of validation errors — use an extension like "errors": [{"field": "email", "message": "invalid format"}]. Here's a realistic example for a SaaS billing API:

``java @ExceptionHandler(PaymentDeclinedException.class) public ProblemDetail handlePaymentDeclined(PaymentDeclinedException ex) { ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.PAYMENT_REQUIRED); pd.setTitle("Payment Declined"); pd.setDetail("Transaction failed due to insufficient funds"); pd.setType(URI.create("https://api.billing.com/errors/payment-declined")); pd.setProperty("x-error-code", "INSUFFICIENT_FUNDS"); pd.setProperty("x-account-id", ex.getAccountId()); pd.setProperty("x-balance", ex.getBalance()); pd.setProperty("x-retry-after", 30); return pd; } ``

Output: ``json {"type":"https://api.billing.com/errors/payment-declined","title":"Payment Declined","status":402,"detail":"Transaction failed due to insufficient funds","instance":"/api/charges","x-error-code":"INSUFFICIENT_FUNDS","x-account-id":"acc_12345","x-balance":5.00,"x-retry-after":30} ``

@ExceptionHandler(PaymentDeclinedException.class)
public ProblemDetail handlePaymentDeclined(PaymentDeclinedException ex) {
    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.PAYMENT_REQUIRED);
    pd.setTitle("Payment Declined");
    pd.setDetail("Transaction failed due to insufficient funds");
    pd.setType(URI.create("https://api.billing.com/errors/payment-declined"));
    pd.setProperty("x-error-code", "INSUFFICIENT_FUNDS");
    pd.setProperty("x-account-id", ex.getAccountId());
    pd.setProperty("x-balance", ex.getBalance());
    pd.setProperty("x-retry-after", 30);
    return pd;
}

Global Consistency with ErrorResponse and ProblemDetail

Spring Boot 3.2+ introduced ErrorResponse interface that ProblemDetail implements. This allows you to centralize error handling. Create a base exception class implementing ErrorResponse to ensure every exception has a consistent structure. For a real-time analytics API handling millions of requests, consistency is critical — clients write parsers once. Here's the pattern: define a ApiException that returns a ProblemDetail, then throw it anywhere:

```java public class ApiException extends RuntimeException implements ErrorResponse { private final HttpStatus status; private final String errorCode; private final URI type;

public ApiException(HttpStatus status, String errorCode, String detail) { super(detail); this.status = status; this.errorCode = errorCode; this.type = URI.create("https://api.example.com/errors/" + errorCode); }

@Override public ProblemDetail getBody() { ProblemDetail pd = ProblemDetail.forStatus(status); pd.setTitle(errorCode.replace("_", " ")); pd.setDetail(getMessage()); pd.setType(type); pd.setProperty("x-error-code", errorCode); return pd; } } ```

Then in a controller: ``java if (queryTimeout) { throw new ApiException(HttpStatus.GATEWAY_TIMEOUT, "QUERY_TIMEOUT", "Query exceeded 30s limit"); } ``

Output: ``json {"type":"https://api.example.com/errors/QUERY_TIMEOUT","title":"QUERY TIMEOUT","status":504,"detail":"Query exceeded 30s limit","instance":"/api/analytics/events","x-error-code":"QUERY_TIMEOUT"} ``

public class ApiException extends RuntimeException implements ErrorResponse {
    private final HttpStatus status;
    private final String errorCode;
    private final URI type;

    public ApiException(HttpStatus status, String errorCode, String detail) {
        super(detail);
        this.status = status;
        this.errorCode = errorCode;
        this.type = URI.create("https://api.example.com/errors/" + errorCode);
    }

    @Override
    public ProblemDetail getBody() {
        ProblemDetail pd = ProblemDetail.forStatus(status);
        pd.setTitle(errorCode.replace("_", " "));
        pd.setDetail(getMessage());
        pd.setType(type);
        pd.setProperty("x-error-code", errorCode);
        return pd;
    }
}

Extending ProblemDetail for Custom Fields

The default RFC 7807 structure covers the basics, but real-world APIs almost always need additional context. For example, in a payment-processing system, when a charge fails, you might want to include the payment_intent_id, decline_code, and retry_after seconds. Spring Boot 3.1+ makes this trivial by subclassing ProblemDetail. Here's the hard truth: most teams get this wrong by shoving everything into the "detail" field as a JSON string, which defeats the purpose of a standardized structure. Instead, create a PaymentProblemDetail that extends ProblemDetail and adds typed fields. Use a static factory method to enforce consistency. For example: PaymentProblemDetail.forDeclinedCharge(paymentIntentId, declineCode, retryAfterSeconds). This ensures every error response has a predictable shape. In your @ExceptionHandler, return this custom type directly. Spring will serialize it correctly, including the extra fields, as long as you use Jackson's @JsonUnwrapped or rely on the base class's properties map. I've seen teams waste hours debugging because they forgot to register the custom serializer. Don't. Just extend and use the properties map from ProblemDetail — it's designed for this. One gotcha: the properties map is not thread-safe by default, so in a reactive stack like WebFlux, you need to ensure you're not sharing instances across threads. Use a factory method that creates a new instance per request.

public class PaymentProblemDetail extends ProblemDetail {

    public PaymentProblemDetail(int status, String title, String detail) {
        super(status);
        setTitle(title);
        setDetail(detail);
    }

    public static PaymentProblemDetail forDeclinedCharge(String paymentIntentId, String declineCode, int retryAfterSeconds) {
        PaymentProblemDetail problem = new PaymentProblemDetail(402, "Payment Declined", "The charge was declined by the issuer.");
        problem.setProperty("payment_intent_id", paymentIntentId);
        problem.setProperty("decline_code", declineCode);
        problem.setProperty("retry_after", retryAfterSeconds);
        return problem;
    }
}

Global Exception Handler with ProblemDetail

The standard approach is a @RestControllerAdvice that catches exceptions and returns ProblemDetail. But here's the problem: many tutorials show you how to handle MethodArgumentNotValidException by returning a generic 400 Bad Request. In a real SaaS billing API, you need to return validation errors as a list of problems, not a single one. RFC 7807 supports this with the 'errors' array extension. Spring Boot's ErrorResponse interface makes this clean. Create a handler for ValidationException that builds a ProblemDetail with status 422 and a list of field-level errors in the properties map. I've seen teams try to use BindingResult directly in the handler, which works but leaks framework internals. Instead, wrap it in a domain-specific ValidationErrorResponse. Another trap: @ExceptionHandler methods must return ProblemDetail or ResponseEntity<ProblemDetail> — if you return a raw ResponseEntity, Spring will not apply the media type application/problem+json automatically. Always set the Content-Type header explicitly in production. For 500 errors, never expose stack traces in the response. Use a generic 'Internal Server Error' and log the full stack trace server-side. I once had a junior dev accidentally expose database connection strings in a production error response because they returned e.getMessage() directly. Don't be that person.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ValidationException.class)
    public ProblemDetail handleValidation(ValidationException ex) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
        problem.setTitle("Validation Failed");
        problem.setDetail("One or more fields failed validation.");
        problem.setProperty("errors", ex.getErrors().stream()
            .map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
            .collect(Collectors.toList()));
        return problem;
    }

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleGeneric(Exception ex) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
        problem.setTitle("Internal Server Error");
        problem.setDetail("An unexpected error occurred.");
        log.error("Unexpected error", ex);
        return problem;
    }
}

Integrating with Spring Security Exceptions

Spring Security exceptions like AccessDeniedException and AuthenticationException are notoriously tricky to handle because they occur before your @ControllerAdvice is invoked. The default behavior returns a generic 403 or 401 HTML page, which is useless for a REST API. You must configure the ExceptionTranslationFilter to use a custom AuthenticationEntryPoint and AccessDeniedHandler that return ProblemDetail. Here's the hard truth: most teams forget to set the media type to application/problem+json in these handlers, so clients get a plain text response. In Spring Boot 3.2+, you can use ProblemDetail directly in the commence() method. For authentication failures, return a 401 with a ProblemDetail that includes a 'realm' property. For authorization failures, return a 403 with a detail explaining the missing permission. I've seen production outages where a 403 was returned without any body, and the frontend team spent hours debugging why the error wasn't showing. Always include a 'required_role' or 'missing_permission' property to help clients. Another gotcha: if you're using method security (@PreAuthorize), the exception is thrown inside the controller advice scope, so your @ExceptionHandler will catch it — but only if you've registered it correctly. Test this with a mock security context. Don't assume it works.

@Component
public class SecurityProblemHandler implements AuthenticationEntryPoint, AccessDeniedHandler {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.UNAUTHORIZED);
        problem.setTitle("Authentication Required");
        problem.setDetail("Full authentication is required to access this resource.");
        problem.setProperty("realm", "MyApp");
        writeResponse(response, problem);
    }

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       AccessDeniedException accessDeniedException) throws IOException {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.FORBIDDEN);
        problem.setTitle("Access Denied");
        problem.setDetail("You do not have permission to perform this action.");
        problem.setProperty("required_role", "ADMIN");
        writeResponse(response, problem);
    }

    private void writeResponse(HttpServletResponse response, ProblemDetail problem) throws IOException {
        response.setContentType("application/problem+json");
        response.setStatus(problem.getStatus());
        new ObjectMapper().writeValue(response.getOutputStream(), problem);
    }
}

Testing ProblemDetail Responses

You can't ship a robust API without testing your error responses. The naive approach is to test only the happy path. In a billing system, you need to verify that a 402 Payment Required returns exactly the right ProblemDetail structure. Use MockMvc or WebTestClient (for WebFlux) to send requests that trigger exceptions and assert on the response body. The key is to use jsonPath to verify individual fields like $.title and $.status. But here's the gotcha: Spring's default ProblemDetail serialization includes type as "about:blank" when not set explicitly. If you change it, your tests must account for that. I've seen teams write brittle tests that fail because they hardcoded "about:blank" and later customized the type. Use @Nested test classes to organize tests by exception type. Another mistake: testing only the structure, not the values. Always assert that the detail field contains meaningful information, not just a generic string. For example, when testing a validation error, assert that the 'errors' array includes the exact field name and message. Use @ParameterizedTest to test multiple scenarios. In production debugging, a well-tested error response can save hours of investigation. One more thing: don't forget to test the media type. Use andExpect(content().contentType("application/problem+json")).

@WebMvcTest(controllers = PaymentController.class)
class ProblemDetailTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void shouldReturnProblemDetailForValidationError() throws Exception {
        mockMvc.perform(post("/api/charges")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"amount\": -5}"))
            .andExpect(status().isUnprocessableEntity())
            .andExpect(content().contentType("application/problem+json"))
            .andExpect(jsonPath("$.title").value("Validation Failed"))
            .andExpect(jsonPath("$.status").value(422))
            .andExpect(jsonPath("$.errors[0].field").value("amount"))
            .andExpect(jsonPath("$.errors[0].message").value("must be greater than 0"));
    }

    @Test
    void shouldReturnProblemDetailForUnauthorized() throws Exception {
        mockMvc.perform(get("/api/admin/users"))
            .andExpect(status().isUnauthorized())
            .andExpect(content().contentType("application/problem+json"))
            .andExpect(jsonPath("$.title").value("Authentication Required"))
            .andExpect(jsonPath("$.realm").value("MyApp"));
    }
}