Spring Boot 4 Microservices & REST APIs · Lesson

Problem Details (RFC 7807)

Return standardized error responses.

Problem Details (RFC 7807) is a free Spring Boot 4 Microservices & REST APIs lesson on CoddyKit. This is lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Microservices & REST APIs learning path, and your progress syncs across the web and the CoddyKit app. The Spring Boot 4 Microservices & REST APIs course includes 4 lessons in total.

A Standard for API Errors

Every team inventing its own error JSON leads to chaos for API consumers. RFC 7807 defines Problem Details — a standard, machine-readable error format with a media type of application/problem+json.

The Problem Details Fields

The standard defines a small set of fields:

type — a URI identifying the problem kind
title — short, human-readable summary
status — the HTTP status code
detail — specifics for this occurrence
instance — URI of the specific occurrence

Spring’s ProblemDetail

Spring Framework 6 / Boot 3 ship a built-in ProblemDetail class that models RFC 7807 directly. You construct it with a status and customize the standard fields.

ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        HttpStatus.NOT_FOUND, "Order 42 was not found");
pd.setTitle("Order Not Found");
pd.setType(URI.create("https://errors.example.com/order-not-found"));

Returning ProblemDetail

Return a ProblemDetail from a controller or exception handler. Spring serializes it as application/problem+json with the right status.

@ExceptionHandler(OrderNotFoundException.class)
public ProblemDetail handle(OrderNotFoundException ex) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        HttpStatus.NOT_FOUND, ex.getMessage());
    pd.setTitle("Order Not Found");
    return pd;
}

Enabling Built-in Problem Details

Spring Boot can convert its own framework exceptions into Problem Details automatically when you enable the property, giving consistent errors even for built-in failures.

spring:
  mvc:
    problemdetails:
      enabled: true

Extending with Custom Properties

RFC 7807 permits extension members. Add domain-specific data — an error code, a correlation id, or field errors — via setProperty.

pd.setProperty("errorCode", "ORDER_NOT_FOUND");
pd.setProperty("correlationId", correlationId);
pd.setProperty("timestamp", Instant.now());

ResponseEntityExceptionHandler

Extend ResponseEntityExceptionHandler in your @ControllerAdvice to inherit handlers for Spring’s standard exceptions, then override the hooks to shape them as Problem Details.

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
    // override protected handle... methods to customize
}

Problem Details for Validation

Override the validation hook to express field errors as a Problem Details body with an extension array, giving clients structured, standard validation feedback.

@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
        MethodArgumentNotValidException ex, HttpHeaders h,
        HttpStatusCode status, WebRequest req) {
    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
    pd.setTitle("Validation Failed");
    pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
        .map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
        .toList());
    return ResponseEntity.badRequest().body(pd);
}

Why the type URI Matters

The type URI gives each problem a stable identity clients can branch on — more robust than parsing human text. Point it at documentation describing the error and how to recover.

Content Negotiation

Problem Details responses carry the application/problem+json content type. Clients can detect this media type to distinguish structured errors from normal success payloads.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{ "type": "...", "title": "Order Not Found", "status": 404, "detail": "..." }

Adopting the Standard

Using Problem Details makes your API errors predictable and interoperable:

One shape across all endpoints and frameworks
Machine-readable type for client logic
Extensible for domain-specific detail

Quick Check

Test your understanding of RFC 7807.

Recap

Problem Details standardize API errors.

RFC 7807 defines type, title, status, detail, instance
Spring’s ProblemDetail models it; served as application/problem+json
Enable built-in conversion via spring.mvc.problemdetails.enabled
Add extension members with setProperty
Extend ResponseEntityExceptionHandler to shape framework errors

Frequently Asked Questions

Is the “Problem Details (RFC 7807)” lesson free?

Yes — the full text of “Problem Details (RFC 7807)” is free to read here on the web. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Microservices & REST APIs course, upgrade to CoddyKit PRO. The Spring Boot 4 Microservices & REST APIs course includes 4 lessons in total.

What will I learn in “Problem Details (RFC 7807)”?

Return standardized error responses. You practise Spring Boot 4 Microservices & REST APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Microservices & REST APIs?

No prior experience is required. Spring Boot 4 Microservices & REST APIs on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

How long does the “Problem Details (RFC 7807)” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Microservices & REST APIs lesson?

Yes. Every Spring Boot 4 Microservices & REST APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Spring Boot 4 Microservices & REST APIs