What is RFC 9457 Problem Details and how does it work?
RFC 9457 defines a JSON object, served with the media type application/problem+json, that describes an HTTP error in a machine-readable way. It obsoletes RFC 7807 but keeps the same members and media type, so a valid RFC 7807 document is still valid under RFC 9457. The newer RFC mostly clarifies wording and adds guidance, including a registry for common problem types.
The standard members are:
| Member | Meaning |
|---|---|
type |
URI identifying the problem category. Clients branch on this value. It defaults to about:blank. |
title |
Short summary of the type. It stays constant across occurrences. |
status |
HTTP status code, repeated as advice for clients that only see the body. |
detail |
Explanation specific to this occurrence. |
instance |
URI identifying this specific occurrence. |
about:blank means "no more semantics than the status code." In that case title should match the standard status phrase.
Minimal example
A 404 response carries Content-Type: application/problem+json and a body with type set to about:blank, title set to "Not Found", status set to 404, detail set to "Order 8812 does not exist", and instance set to /orders/8812.
Request flow
- Client → gateway or proxy. Errors such as rate limiting, oversized bodies, TLS failures or upstream timeouts are often answered here. These responses typically use HTML or a vendor JSON shape, which bypasses your format.
- Gateway → application. Framework-level failures that happen before routing completes can also escape your handler.
- Application → centralized exception handler. Exceptions are mapped to problem details in one place.
- Handler → client. The response is returned as
application/problem+json.
A single handler covers only step 3. Clients therefore need defensive parsing until you also configure gateway error bodies to use the same format.
# Minimal problem details response (about:blank: no semantics beyond the status code)
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Order 8812 does not exist",
"instance": "/orders/8812"
}
# Request flow: where error bodies are produced
Client
| GET /orders/8812
v
Gateway / proxy -----------> 413, 429, 502, 504, TLS errors
| HTML or vendor JSON body
| (BYPASSES problem+json)
v
Application framework -----> errors raised before routing completes
| default framework error body
| (CAN BYPASS problem+json)
v
Route handler
| throws OrderNotFound
v
Centralized exception handler
| maps exception -> type, title, status, detail, instance
v
Client <---- 404 application/problem+json
A minimal RFC 9457 404 response with its Content-Type header and standard members, followed by a request flow showing how gateway-generated and pre-routing framework errors can return bodies that bypass the centralized problem+json handler.
Why use problem details as your single API error format, and who should adopt it?
The format itself is the least interesting part. Any team can agree to emit JSON with type, title, status, detail and instance. The return comes from treating the type URIs and extension members as a versioned, documented interface, held to the same compatibility rules as your resource schemas. A client that branches on type is depending on that string as a contract. If one service renames it or quietly changes the shape of an extension member, that client breaks.
When the contract is stable, three things improve:
- Shared client error handling. One parser and one dispatch table keyed on
typework across every service. SDKs, frontends and partner integrations stop carrying a separate error branch for each endpoint. - Consistent tooling. Logging, alerting, gateway policies and API documentation can all rely on the same fields. A dashboard can group failures by
typewithout per-service mapping rules. - Fewer repeated design decisions. Without a shared format, every new endpoint reopens the same questions: where the message goes, how field errors nest, whether to include a code. With one format, that work happens once at the platform level and individual teams only define new
typevalues.
The best fit is any API whose error handling is written by people other than the API's authors. That covers public APIs, platforms where many teams publish services behind one gateway, and APIs consumed by several client implementations in different languages. In each case, every inconsistency in the error format gets paid for again in each client codebase, so standardizing removes that duplicated parsing work.
How should you design type URIs, titles and details?
The type member is the error's identity. Clients branch on it, so treat it like a public enum value: once published, never rename or repurpose it. Use absolute URIs, because relative ones resolve against the request URL and can produce different strings for the same error.
You then choose whether the URI resolves to a page.
| Choice | Example | Gains | Costs |
|---|---|---|---|
| Dereferenceable | ` | Developers can open it and read causes and fixes | You must host the pages, keep them online and keep them accurate |
| Non-resolvable | tag:example.com,2024:problems/insufficient-funds |
No hosting commitment | Clients get an identifier and nothing else |
Both are valid under RFC 9457. A broken documentation link costs you more trust than having no link, so make a URI dereferenceable only if someone owns the page. Clients should not fetch the URI at runtime either way.
title is a short summary that stays fixed for a given type, such as "Insufficient funds." detail describes this specific occurrence, such as "Balance is 30.00; transfer requires 45.00." It is written for humans. Clients must never parse it. If a client needs a value from it, add an extension member that carries the value directly.
Localization creates a tension here. The RFC allows title to vary by language, but a client that logs or compares titles will then see different strings for the same error. Translate title and detail according to Accept-Language, and tell clients to key their logic on type.
Check what your framework produces by default. Many emit type: about:blank with a title such as "Bad Request." The response is valid, but it gives clients nothing beyond what the status code already told them.
How do you model validation errors and other extension members?
Extension members carry the contract
type, title, status, detail and instance tell a client what kind of failure occurred. Anything a program needs in order to act on the failure goes in extension members, and RFC 9457 leaves their names and shapes entirely to you. Because the spec requires clients to ignore extensions they don't recognize, you can add members later without breaking anyone. That also means nothing in the spec enforces consistency, so you have to define the conventions yourself.
Validation errors and correlation IDs
Use one shape everywhere. A common choice is an errors array in which each entry has a pointer (a JSON Pointer into the request body), a machine-readable code, and a human-readable detail. Add a top-level traceId or correlationId member whose value matches the one in your logs. Support teams can then go from a client's bug report to the server trace without asking for timestamps.
Multiple problems
The errors array is how you report several problems of the same type, such as ten invalid fields in one request. RFC 9457 defines no way to combine different problem types in a single response. If a request fails both authorization and validation, return the most relevant problem and leave out the others.
Status and Content-Type
The status member is advisory, and it must match the actual HTTP status code. Proxies and gateways sometimes rewrite status codes without touching the body, so take both values from the same source in your code.
Send Content-Type: application/problem+json. If the client's Accept header excludes that type but allows application/json, return the same body labeled application/json. Avoid responding with 406 Not Acceptable in that case, because it replaces the real error with a negotiation failure.
import express, { NextFunction, Request, Response } from "express";
import { randomUUID } from "node:crypto";
const app = express();
app.use(express.json());
// Attach one correlation ID per request; log it and echo it in problems.
app.use((req: Request, res: Response, next: NextFunction) => {
res.locals.traceId = req.get("X-Request-Id") ?? randomUUID();
next();
});
interface FieldError { pointer: string; code: string; detail: string; }
function sendValidationProblem(req: Request, res: Response, errors: FieldError[]) {
const status = 422; // Single source for both the HTTP status and the body member.
const body = {
type: "",
title: "Request body failed validation",
status,
detail: `${errors.length} field(s) failed validation.`,
traceId: res.locals.traceId, // Matches the ID written to server logs.
errors, // Many problems of the same type go in one extension array.
};
// Prefer problem+json. If the client only accepts application/json, send the
// same body under that label instead of replacing the error with a 406.
const contentType =
req.accepts(["application/problem+json", "application/json"]) || "application/problem+json";
res.status(status).type(contentType).send(JSON.stringify(body));
}
app.post("/orders", (req: Request, res: Response) => {
const errors: FieldError[] = [];
if (typeof req.body?.quantity !== "number") {
errors.push({ pointer: "/quantity", code: "type_number", detail: "quantity must be a number." });
}
if (!req.body?.sku) {
errors.push({ pointer: "/sku", code: "required", detail: "sku is required." });
}
if (errors.length > 0) return sendValidationProblem(req, res, errors);
res.status(201).json({ ok: true });
});
app.listen(3000);
An Express handler that returns all per-field validation errors in one errors array with a correlation ID, takes status and the HTTP status code from the same variable, and falls back to application/json when the client does not accept application/problem+json.
How do you implement RFC 9457 in Spring with ProblemDetail?
Spring's ProblemDetail class models the RFC 9457 members directly. Build one with ProblemDetail.forStatusAndDetail(status, detail), then call setType, setTitle and setInstance for the standard members. Extension members go through setProperty(name, value), which serializes them at the top level of the JSON object rather than nesting them. Return the object from an @ExceptionHandler method in a @RestControllerAdvice class. Spring writes it as application/problem+json and uses the status field as the HTTP status code, so the two cannot drift apart.
Centralizing handlers matters because the framework raises its own exceptions before your controllers run, such as MethodArgumentNotValidException for failed validation and HttpMediaTypeNotSupportedException for an unsupported Content-Type. If your advice class extends ResponseEntityExceptionHandler, those exceptions already produce ProblemDetail bodies. You can override hooks like handleMethodArgumentNotValid to replace the default type with your own URI and attach the errors extension from section 4. Without that override, validation failures would carry Spring's generic defaults while your domain errors carry your catalog, which gives clients two formats.
Spring Boot exposes a spring.mvc.problemdetails.enabled property that turns on this behavior without a custom advice class. Confirm in the reference documentation for your Boot version that the property exists and what it covers.
Finally, add a catch-all @ExceptionHandler(Exception.class). It should return a 500 with a fixed, generic detail and never call exception.getMessage(), which can leak SQL fragments, hostnames or internal IDs. Read the correlation ID from your request context, write it to the log alongside the full stack trace, and expose only that ID as an extension member so support can match a client report to the server log.
// Imports omitted. Assumes a servlet filter puts "correlationId" into the SLF4J MDC.
@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);
private static final String TYPES = "";
// Domain error: every standard member set explicitly, plus one extension member.
@ExceptionHandler(OrderNotFoundException.class)
ProblemDetail orderNotFound(OrderNotFoundException ex, HttpServletRequest req) {
ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, "Order " + ex.getOrderId() + " does not exist.");
pd.setType(URI.create(TYPES + "order-not-found"));
pd.setTitle("Order not found");
pd.setInstance(URI.create(req.getRequestURI()));
pd.setProperty("orderId", ex.getOrderId()); // serialized at top level, not nested
return pd;
}
// Framework error: reuse Spring's ProblemDetail but swap in our type and errors extension.
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
HttpHeaders headers, HttpStatusCode status, WebRequest request) {
ProblemDetail pd = ex.getBody();
pd.setType(URI.create(TYPES + "validation-error"));
pd.setTitle("Request validation failed");
pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
.map(e -> Map.of("field", e.getField(), "message", String.valueOf(e.getDefaultMessage()))).toList());
return handleExceptionInternal(ex, pd, headers, status, request);
}
// Fallback: fixed detail, never ex.getMessage(); full stack trace goes to the log only.
@ExceptionHandler(Exception.class)
ProblemDetail unexpected(Exception ex) {
String correlationId = MDC.get("correlationId");
log.error("Unhandled exception correlationId={}", correlationId, ex);
ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred.");
pd.setType(URI.create(TYPES + "internal-error"));
pd.setTitle("Internal server error");
pd.setProperty("correlationId", correlationId); // lets support match the response to the log line
return pd;
}
}
A @RestControllerAdvice extending ResponseEntityExceptionHandler that builds a domain ProblemDetail, rewrites Spring's validation ProblemDetail to use the same type catalog and errors extension, and adds a sanitized 500 fallback that logs the stack trace with a correlation ID.
When should you avoid problem details, and what are the alternatives?
Problem details is an HTTP convention. It pays off when many independent clients need one predictable error shape. Elsewhere it adds little.
| Format | Where it fits | Main drawback |
|---|---|---|
| Ad hoc custom JSON | Small APIs with a single team | Each endpoint invents its own fields, so clients need endpoint-specific parsing |
| Framework default bodies | Prototypes | The shape can change on upgrade and may expose exception class names |
Envelope (data/error on every response) |
RPC-style APIs that always return 200 | Caches, proxies and monitoring can't see failures in the status code |
| gRPC status | gRPC services | Not HTTP; it has its own code, message and details model |
GraphQL errors array |
GraphQL APIs | Errors sit beside partial data, which a single problem document can't express |
Skip problem details in three cases:
- Internal API with one client deployed in lockstep. A shared error type in both codebases is simpler.
- Non-HTTP protocols. Use the protocol's native error model instead.
- Clients you cannot update. Keep the old format, and offer
application/problem+jsononly through content negotiation or a new API version.
If you adopt it, plan for three trade-offs:
- Other components write their own error bodies. Gateways, load balancers and client libraries generate 429, 502 and timeout responses in their own format. Clients should check
Content-Typebefore parsing as a problem document. - Clients may depend on
detailwording. Any client that branches ondetailtext will break when you reword it. Document that onlytypeand named extension members are stable. - Detailed errors can leak information. "No account for this email" lets attackers confirm which accounts exist. Where existence is sensitive, return the same problem for "not found" and "forbidden".
How do you migrate, test and document your error contract without breaking clients?
Any client that parses your current error body depends on its shape, so replacing that shape is a breaking change even when the status codes stay the same. There are three common ways to migrate:
- Version the API. Ship problem details only in the new version. This is the cleanest option, but it is also the slowest.
- Negotiate on
Accept. Returnapplication/problem+jsonto clients that ask for it and the legacy shape to everyone else. Many clients send*/*orapplication/json, though, so most traffic will stay on the old format until each client opts in. - Emit both temporarily. Add the problem members next to the legacy fields, then remove the legacy fields after a deprecation window you announce in advance.
Every dual-format option has an ongoing cost. Each new error needs both shapes, and both shapes need tests. Set a removal date before you start.
Illustrative estimate. Assume dual output takes 4 developer-days to build and 1 day per month to maintain. Assume 10 consuming teams each save 2 hours per month because they no longer write per-endpoint error parsing, which comes to roughly 2.5 days per month. Under those assumptions you break even in about three months. If you have fewer consumers or a longer overlap period, the result can come out the other way.
In OpenAPI, define a shared Problem schema under components. Extend it with allOf for each problem type that adds members, such as a validation type with an errors array. Reference the extended schemas from responses under the application/problem+json media type. Document each type URI and its extension members in that type's description.
Your contract tests should assert:
- the
Content-Typeheader - that
statusmatches the HTTP status - that
typecomes from the documented set - that every required extension member is present
Don't assert on detail text. It is meant for humans and should be free to change.
components:
schemas:
Problem: # shared RFC 9457 members; all optional per the RFC
type: object
properties:
type: { type: string, format: uri-reference, default: 'about:blank' }
title: { type: string }
status: { type: integer, minimum: 100, maximum: 599 }
detail: { type: string }
instance: { type: string, format: uri-reference }
additionalProperties: true # clients must ignore unknown extension members
ValidationProblem:
description: >
type
Extension member `errors` lists each invalid field.
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
required: [errors]
properties:
errors:
type: array
items:
type: object
required: [pointer, detail]
properties:
pointer: { type: string, description: JSON Pointer to the invalid field }
detail: { type: string }
responses:
ValidationFailed:
description: Request body failed validation.
content:
application/problem+json: # media type contract tests assert on
schema: { $ref: '#/components/schemas/ValidationProblem' }
example:
type:
title: Your request is not valid.
status: 422
errors:
- { pointer: /email, detail: must be a valid email address }
An OpenAPI components fragment that defines a shared Problem schema, extends it with allOf into a validation problem type with an errors extension member, and references it from a response served as application/problem+json.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to rfc 9457 problem details, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.