Problem Details: The Standard Error Body

RFC 9457 defines five fields and a media type, so an API need not invent its own error format.

Problem details, defined in RFC 9457, is a standard JSON format for HTTP error bodies. It has five fields, type, title, status, detail and instance, and its own media type, application/problem+json, so a client knows from the Content-Type header that the body describes a problem. An API can add fields of its own, called extension members, for anything more.

text

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/out-of-stock",
  "title": "Product out of stock",
  "status": 409,
  "detail": "Only 2 of pen-blue are left; 3 were requested.",
  "instance": "/orders/attempts/8f2c",
  "available": 2
}

An illustrative problem details response for an order that cannot be fulfilled

type is a URI naming the kind of problem, and the field a client branches on. It should not change between releases. It may point at a documentation page describing the problem. When no type is given, it defaults to about:blank, meaning the status code says everything.

title is a short, human-readable summary of the type. It is the same for every occurrence of that type, but may be translated or reworded, so programs should not compare it.

status repeats the HTTP status code, so the body is complete if it is logged or passed on without its headers.

detail explains this occurrence: which product, how many were left. It is for people, and it changes from one response to the next.

instance is a URI identifying this occurrence, useful when someone reports it to support.

Extension members carry data a client can act on, such as available here, so the client can offer to order 2 instead of reading the number from detail.

RFC 9457 replaced the earlier RFC 7807 in 2023 with the same fields, and added a registry of common problem types.

So return problem details from every endpoint, branch on type, and put the data a client needs in extension members, not in prose.

← → move through sections and cards