What is RFC 9457 problem details, and how does it relate to RFC 7807?
RFC 9457 defines a standard JSON (and XML) body for HTTP error responses. The goal is narrow: give clients a predictable way to learn what kind of problem occurred and where to read more about it, without every API inventing its own envelope of error, errors, message, or code fields. A problem details object is a small document with a few well-known members, such as a type identifier, a short title, and the HTTP status. It is served with the application/problem+json or application/problem+xml media type, so a client can recognize it from the Content-Type header before parsing the body.
RFC 9457 obsoletes RFC 7807 but does not replace its model. The members, their meanings, and both media types are unchanged. The revision adds three things:
- Clarifications to wording that implementers had read in different ways, particularly around how type URIs should be used and interpreted.
- Guidance on multiple problems. When a request fails for several reasons of the same type, list them in an extension member. When the reasons differ in kind, return the most relevant or urgent one rather than inventing a composite format.
- A registry of common problem types, so generic errors can share identifiers instead of each API minting its own.
Any response that conformed to RFC 7807 still conforms to RFC 9457, and clients written against 7807 keep working.
This guide treats the format as an API contract rather than a JSON shape. The format pays off only when type identifiers stay stable, extensions are documented, and clients can depend on both.
How do the five standard members work, and which should clients rely on?
The response carries Content-Type: application/problem+json and a JSON object made of the members below. A typical body for a declined payment has type set to title"Insufficient funds",status402,detail"Account balance is 12.40; the charge requires 30.00.", andinstanceset to/payments/8f3a`.
| Member | Kind | Who reads it | Client should |
|---|---|---|---|
type |
URI reference | Code | Branch on it |
title |
Short summary of the type | Humans | Show or log it, never parse it |
status |
Integer | Code, logs | Treat it as advisory |
detail |
Text about this specific occurrence | Humans | Show or log it, never parse it |
instance |
URI reference for this occurrence | Support, logs | Correlate it with server logs |
Only type is a contract. Translators and support engineers can reword title and detail at any time. If a client matches on strings like "Insufficient funds", the next copy edit becomes a breaking change. When type is absent, its value defaults to about:blank. That tells the client nothing beyond the HTTP status code.
status duplicates the status line. It exists so the code survives when someone stores or forwards the body without its headers. It must match the real status. The trouble is that gateways, CDNs and load balancers sometimes rewrite a 503 into a 502, or turn a 4xx into a generic error page, and leave the body as it was. The status line is authoritative. Clients should trust it whenever the two disagree.
Set Content-Type explicitly on every error path, including framework-generated 404s and 405s. Many stacks default those to text/html. If the client's Accept header lists neither application/problem+json nor a wildcard, still return the problem document. Responding with a 406 would hide the original failure behind a negotiation error.
// Client handling of an RFC 9457 problem response for a declined payment.
type Problem = { type?: string; title?: string; status?: number; detail?: string; instance?: string };
class InsufficientFundsError extends Error {
constructor(detail?: string, public instance?: string) { super(detail ?? "Insufficient funds"); }
}
async function charge(payload: unknown): Promise<void> {
const res = await fetch("", {
method: "POST",
headers: {
"Content-Type": "application/json",
// Ask for problem details explicitly, alongside the normal success type.
Accept: "application/json, application/problem+json",
},
body: JSON.stringify(payload),
});
if (res.ok) return;
// Parse as a problem only if the server says it is one. A gateway may have
// swapped the body for an HTML error page.
const ct = (res.headers.get("Content-Type") ?? "").toLowerCase();
if (!ct.startsWith("application/problem+json")) throw new Error(`HTTP ${res.status}`);
const p: Problem = await res.json();
const type = p.type ?? "about:blank"; // an absent type means about:blank
// The status line is authoritative. The body's status is advisory.
if (p.status !== undefined && p.status !== res.status) {
console.warn(`status mismatch: line=${res.status} body=${p.status}`);
}
// Branch on type only. Never match on title or detail text.
if (type === "") {
throw new InsufficientFundsError(p.detail, p.instance);
}
// Log the human-readable text and instance so support can correlate it with server logs.
console.error(res.status, p.title, p.detail, p.instance);
throw new Error(`HTTP ${res.status}: ${p.title ?? "error"}`);
}
A fetch-based client checks Content-Type, branches only on the problem's type URI, trusts the HTTP status line over the body's status member and logs title, detail and instance.
How should you design type URIs as stable error identifiers?
Treat the type URI as an identifier, like an enum value. Clients compare it as a string, and the spec warns them not to dereference it automatically. Put it under a domain or path you control, for example ` That way no third party can claim or redirect your namespace. Use absolute URIs, because relative ones resolve against the request URL and can end up meaning different things on different endpoints.
Once a type has shipped, never rename it or change its meaning. If the semantics change, mint a new URI and leave the old one alone. Retire types by documenting them as deprecated, not by deleting them, because a client somewhere still matches on that string.
Use about:blank, the default, when the status code says everything the client needs, such as a plain 404 or 405. In that case, set title to the standard status phrase ("Not Found"). Clients may display it, and a custom title would suggest a distinction that the absent type does not actually make.
| Choice | Benefit | Cost |
|---|---|---|
| Resolvable URI | Developers can paste it into a browser and find docs | Every page must stay current. A 404 or stale page erodes trust |
| Non-resolving URI | No documentation to maintain | No discoverability, so docs must be found elsewhere |
| Fine-grained types | Precise client branching | The catalog grows and becomes hard to keep consistent |
| Coarse types | A small, stable catalog | Clients go back to parsing detail text |
For granularity, create one type per distinct action a client would take, not one per code path in your server.
How do you add extension members and report validation errors?
Extension members are top-level fields beyond the five standard ones. They carry the data a client needs to act without parsing prose. The RFC requires clients to ignore extensions they don't recognize. That rule lets you add a field to an existing type without breaking older consumers. It also means a client can't be required to understand a new extension, so the standard members must still make sense on their own. For portability, the RFC recommends that extension names start with a letter, contain only letters, digits and underscores, and be at least three characters long.
Common extensions:
errors: an array of field-level issues. Each entry holds adetailand apointer, where the pointer is a JSON Pointer to the offending field in the request body.- A retry hint, such as seconds until a rate limit resets. Keep it consistent with any
Retry-Afterheader so the two never disagree. - A trace or correlation ID, so support staff can find the request in logs without asking the caller for details.
Multiple issues in one response
Don't return a list of problem objects. When the issues share one type, such as several validation failures, return one problem with an errors array. When the issues have different types, the RFC recommends returning the most relevant or urgent one, because a response can't carry two different type values.
Governance
Register every extension name and its schema in the same catalog that defines your types. Without that review, teams invent overlapping fields like traceId, trace_id and requestId, and clients have to handle all three.
Serialization rules
Build detail and extensions from an allowlist of fields. Never serialize exception objects into the response. External responses must not include stack traces, SQL, internal hostnames or upstream error text. Log those details server-side under the correlation ID.
// Internal error: may carry a raw cause (DB driver error, stack, hostnames).
interface FieldIssue { pointer: string; detail: string; }
class ValidationFailure extends Error {
constructor(public issues: FieldIssue[], public cause?: unknown) {
super("validation failed");
}
}
// Build the body from an allowlist. Never spread or JSON.stringify the error.
function toProblem(err: ValidationFailure, traceId: string, instance: string) {
return {
type: "",
title: "Your request is not valid.",
status: 422,
// Written for the caller. Never use err.message, which can echo SQL.
detail: `${err.issues.length} field(s) failed validation.`,
instance,
// Extension: one problem type with many field-level issues, not a list of problems.
// Copy only pointer and detail so stray properties on an issue are dropped.
errors: err.issues.map(({ pointer, detail }) => ({ pointer, detail })),
// Extension: name and schema registered in the shared catalog.
trace_id: traceId,
};
}
// The full error, including stack and cause, goes to logs only.
function report(err: ValidationFailure, traceId: string, instance: string) {
console.error({ trace_id: traceId, stack: err.stack, cause: err.cause });
return {
status: 422,
headers: { "Content-Type": "application/problem+json" },
body: JSON.stringify(toProblem(err, traceId, instance)),
};
}
// Example output body:
// {"type":"","title":"Your request is not valid.",
// "status":422,"detail":"2 field(s) failed validation.","instance":"/orders/7f3a",
// "errors":[{"pointer":"/email","detail":"must be a valid email address"},
// {"pointer":"/items/0/quantity","detail":"must be at least 1"}],
// "trace_id":"4bf92f3577b34da6"}
A serializer builds a single validation problem from an allowlist, with an errors array of JSON Pointer issues and a registered trace_id extension, and sends stack traces and raw causes only to server logs.
How do you implement problem details centrally across services?
Put that rule in one place. Each service should have a single error-mapping layer that sits outermost in its request pipeline. Handlers throw domain exceptions, and only this layer decides what the client sees. A framework-neutral sketch:
- Catch any exception that escapes the handler.
- Map the exception's class or error code to an entry in a shared problem catalog. Each entry holds the
typeURI, defaulttitle,status, and allowed extension members. - Map anything unrecognized to a generic
500entry whosedetailreveals nothing. - Attach
instanceand a correlation ID, and log the full exception server-side under that ID. - Serialize with
Content-Type: application/problem+json.
Publish the catalog as a versioned package or data file that services and gateways both consume. That way a gateway's rate-limit 429 uses the same type URI as a service's 429.
Centralizing saves engineering time because redaction, status-code consistency and catalog lookups are enforced once instead of being reviewed in every handler. It also lets clients write one error parser instead of one per service.
Uniformity still stops at your own code. Several layers can return errors that never pass through your mapper:
- Load balancers and CDNs can return HTML error pages for upstream timeouts.
- Framework defaults often emit plain text for routing misses or bodies that fail to parse.
- Proxies can reject oversized requests before your code runs.
Configure custom error responses wherever a layer allows it. Clients must still check Content-Type before parsing the body.
For localization, you can negotiate Accept-Language and translate title and detail on the server. That keeps clients simple, but every service then carries translations. The alternative is to have clients look up messages keyed on type. That keeps servers language-neutral and gives clients full control over wording.
// Shared catalog: shipped as a versioned package used by services and gateways
type CatalogEntry = { type: string; title: string; status: number; extensions?: string[] };
const catalog: Record<string, CatalogEntry> = {
OUT_OF_CREDIT: { type: "", title: "Insufficient credit", status: 403, extensions: ["balance"] },
RATE_LIMITED: { type: "", title: "Too many requests", status: 429 },
INTERNAL: { type: "", title: "Internal error", status: 500 },
};
class DomainError extends Error {
constructor(public code: string, public detail?: string, public ext: Record<string, unknown> = {}) { super(code); }
}
type Req = { path: string };
type Res = { status: number; headers: Record<string, string>; body: string };
type Handler = (req: Req) => Promise<Res>;
// Outermost layer: the only place that decides what the client sees
export const problemMiddleware = (next: Handler, log: (id: string, e: unknown) => void): Handler =>
async (req) => {
try {
return await next(req);
} catch (err) {
const correlationId = crypto.randomUUID();
log(correlationId, err); // full exception stays server-side
const known = err instanceof DomainError ? catalog[err.code] : undefined;
const entry = known ?? catalog.INTERNAL; // unknown errors reveal nothing
const problem: Record<string, unknown> = { type: entry.type, title: entry.title, status: entry.status, instance: req.path, correlationId };
if (known && err instanceof DomainError) {
if (err.detail) problem.detail = err.detail;
// Redaction: copy only extension members the catalog allows
for (const k of entry.extensions ?? []) if (k in err.ext) problem[k] = err.ext[k];
}
return { status: entry.status, headers: { "Content-Type": "application/problem+json" }, body: JSON.stringify(problem) };
}
};
A framework-neutral middleware that maps domain exceptions to a shared problem catalog, redacts unknown errors to a generic 500, logs under a correlation ID, and emits application/problem+json.
How should API clients parse and handle problem responses?
A client should treat an error response as a sequence of increasingly weak signals and stop at the first one it can trust.
- Check the
Content-Typefirst. Only attempt problem parsing when the media type isapplication/problem+json. Compare it case-insensitively and ignore parameters such ascharset. Proxies, load balancers, gateways and CDNs often return their own HTML or plain-text error pages for 502, 503 and 504 responses. A client that assumes every non-2xx body is a problem object will throw a parse error and hide the real failure. - Branch on
type. If the body parses andtypematches an identifier your client knows, handle that case explicitly, for example by retrying after a rate limit or prompting for re-authentication. Comparetypeas an exact string. Do not dereference it at runtime. - Fall back to the HTTP status. An unknown
type, a missingtype,about:blank, a malformed body or a non-problem body all lead here. Use the status line, not thestatusmember. An intermediary may have changed the status line, and the body member is only advisory.
Keep the raw body, instance, and any trace identifier in your logs whatever the branch. That preserves diagnostics without making them part of control flow.
Never parse detail or title to make decisions. They are written for humans. They may be localized, and servers can reword them at any time. If a client needs to act on a piece of information, it should come from type or a documented extension member.
The example below follows this order. Every unrecognized case degrades to status-based handling instead of an exception.
type Outcome = "retry" | "reauth" | "client-error" | "server-error" | "unexpected";
// Problem type identifiers this client knows. They are compared as strings and never fetched.
const RATE_LIMITED = "";
const TOKEN_EXPIRED = "";
export async function classifyError(res: Response): Promise<Outcome> {
// Read the body as text so HTML or plain-text pages from proxies cannot throw here.
const raw = await res.text();
// 1. Content-Type: ignore parameters such as charset and compare case-insensitively.
const mediaType = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
let problem: Record<string, unknown> | undefined;
if (mediaType === "application/problem+json") {
try {
const parsed: unknown = JSON.parse(raw);
if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
problem = parsed as Record<string, unknown>;
}
} catch {
// A malformed problem body falls through to status-based handling.
}
}
// Log diagnostics on every branch, but keep them out of control flow.
console.warn("HTTP error", { status: res.status, instance: problem?.instance,
traceparent: res.headers.get("traceparent"), body: raw.slice(0, 2000) });
// 2. Branch on type with an exact string match. Never inspect detail or title.
const type = typeof problem?.type === "string" ? problem.type : undefined;
if (type === RATE_LIMITED) return "retry";
if (type === TOKEN_EXPIRED) return "reauth";
// 3. Fall back to the status line (res.status), not the advisory problem.status member.
if (res.status === 429 || res.status === 503) return "retry";
if (res.status === 401) return "reauth";
if (res.status >= 400 && res.status < 500) return "client-error";
if (res.status >= 500) return "server-error";
return "unexpected";
}
A TypeScript client parses a problem body only when Content-Type is application/problem+json, matches known type URIs exactly, and otherwise falls back to the HTTP status line, so non-problem or malformed bodies never throw.
When should you adopt RFC 9457, when should you avoid it, and what are the alternatives?
RFC 9457 pays off when the people reading your errors are not the people writing them. Public APIs, platforms where many teams publish services, and fleets behind a shared gateway gain the most. In those settings, one format lets SDKs, gateways and dashboards handle failures from any service the same way. For an internal API with a single consumer that ships in lockstep with the server, the format adds little: a shared type definition already provides the contract. Protocols with their own error models should keep them, because wrapping them in problem details duplicates information and confuses tooling.
| Approach | Error identity | Best fit | Main drawback |
|---|---|---|---|
| RFC 9457 problem details | type URI plus HTTP status |
HTTP APIs with many consumers | Catalog upkeep |
| Custom JSON envelope | Ad hoc code field | A single consumer you control | Every client needs custom parsing |
GraphQL errors array |
extensions (by convention) |
GraphQL APIs | Usually returned with 200, so status codes carry no error meaning |
| gRPC status with error details | Canonical status code plus typed detail messages | RPC between services | Not native to plain HTTP clients |
Most of the cost comes after the first implementation. Someone has to own the type catalog, review new types before release, and keep the documentation pages accurate. Without that governance, near-duplicate types accumulate and clients lose a reliable identifier.
Migrating from a custom envelope
- Map legacy codes. Build a table from each legacy error code to a type URI.
- Serve both formats. Return
application/problem+jsonto clients that request it inAccept. Keep serving the old envelope to everyone else during an announced deprecation window. - Bridge clients still on legacy fields. Emit the old code as an extension member, so those clients keep working while they move their logic to
type. - Retire the old format. Remove the envelope and the bridging extension once traffic on the legacy format stops.
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.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
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.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- 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.