ProblemDetail / RFC 7807

## The problem RFC 7807 solves Before a standard existed, every REST API returned errors in its own ad-hoc JSON shape (`{"error": "..."}`, `{"message": "...", "code": 42}`, etc.). Clients had to learn each API's quirks. **RFC 7807 'Problem Details for HTTP APIs'** (later superseded by RFC 9457, but Spring's docs still reference 7807) defines one canonical error body so clients and tools can parse errors uniformly. ## The five standard fields `org.springframework.http.ProblemDetail` (introduced in **Spring Framework 6 / Spring Boot 3**) models exactly these fields: - **type** — a URI (as a `java.net.URI`) that identifies the *category* of problem. Default is `about:blank`, which per the spec means 'no specific type; just use the status code'. A real type like `https://api.example.com/errors/out-of-credit` can point to documentation. - **title** — a short, human-readable summary of the problem type. Should stay the same for a given `type` (e.g. 'You do not have enough credit'). - **status** — the HTTP status code as an integer (e.g. `404`), duplicated in the body for convenience. - **detail** — a human-readable explanation *specific to this occurrence* (e.g. 'Your balance is 30 but the cost is 50'). - **instance** — a URI identifying the *specific occurrence* (e.g. `/account/12345/msgs/abc`). All fields are optional per the spec; Spring populates `status` and `title` sensibly by default. ## The media type A ProblemDetail response is sent with `Content-Type: application/problem+json` (constant `MediaType.APPLICATION_PROBLEM_JSON`). The `+json` structured-suffix tells generic tooling it is JSON while the `problem` prefix flags it as an error body. There is also an XML variant, `application/problem+xml`. ## Creating one ```java ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND); pd.setDetail("Order 42 was not found"); pd.setType(URI.create("https://api.example.com/errors/order-not-found")); ``` Factory methods: `forStatus(HttpStatusCode)`, `forStatus(int)`, `forStatusAndDetail(HttpStatusCode, String)`. There is no public constructor you would normally use — go through the factories. ## Extension members RFC 7807 lets you add arbitrary extra fields. In Spring you call `pd.setProperty("balance", 30)` and it is serialized as a top-level JSON member alongside the standard fields. This is how you carry domain-specific data (a correlation id, a list of validation errors, etc.). ## Returning it From a `@RestController` or `@ExceptionHandler` you can return a `ProblemDetail` directly, a `ResponseEntity<ProblemDetail>`, or throw an exception that implements `ErrorResponse`. Spring's message converters serialize it with the correct content type. ## Gotchas - The `type` default `about:blank` is intentional — don't feel obligated to set a URI unless you have stable documentation to point to. - `status` in the body is informational; the *actual* HTTP status is still driven by the response status line / `ResponseEntity`. Keep them consistent. - ProblemDetail is a Spring class, not a JDK class — it lives in `spring-web`, so it is available in both Spring MVC and WebFlux.