Problem Details for HTTP APIs (RFC 9457)

What is Problem Details?

Problem Details for HTTP APIs is a standardized machine-readable format for carrying error information in an HTTP response body. Rather than every API inventing its own ad-hoc error shape, RFC 9457 (which obsoletes the earlier RFC 7807) defines a small, predictable set of members that clients can parse consistently across services.

The format is serialized as JSON using the media type:

Content-Type: application/problem+json

An equivalent XML serialization is defined using application/problem+xml.

1. Standard Members

A problem details object is a JSON object with the following optional members. All members are optional, but a useful response typically includes at least type, title, and status.

The type URI is the primary identifier for the kind of error. When dereferenced it should ideally provide human-readable documentation. If type is absent, it is assumed to be about:blank, and the title should then be the HTTP status phrase.

2. A Full Example

The following describes a request that failed because the account has insufficient credit:

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": ["/account/12345", "/account/67890"]
}

Note that balance and accounts are not standard members — they are extension members, described next.

3. Extension Members

Problem detail objects may include any number of additional members, called extension members, to convey machine-readable context beyond the standard fields. Consumers that do not recognize an extension member must ignore it.

Extension members are what make the format practical. A rate-limit error might add retryAfter; an out-of-stock error might add sku. Because the type URI defines the problem, it also defines which extension members a client can expect.

4. Validation Errors

A common pattern is reporting multiple field-level validation failures in a single response. RFC 9457 does not mandate a specific shape, but the widely used convention is an errors extension array where each entry references a location within the request:

{
  "type": "https://example.com/probs/validation-error",
  "title": "Your request is not valid.",
  "status": 422,
  "detail": "The request body failed validation.",
  "errors": [
    {
      "detail": "must be a positive integer",
      "pointer": "#/quantity"
    },
    {
      "detail": "must be a valid email address",
      "pointer": "#/customer/email"
    }
  ]
}

Here pointer is a JSON Pointer (RFC 6901) into the request body. Some APIs instead use parameter for query/form fields or header for header-based failures.

5. Design Guidance

• Keep type stable. Clients branch on the type URI, so treat it as part of your API contract — changing it is a breaking change.
• Do not leak internals. detail is for the client, not a stack trace. Avoid exposing implementation specifics.
• Mirror the status code. The status member should match the actual HTTP response status so intermediaries and logs agree.
• Document extensions. Every extension member a type can emit should be documented at the type URI.

RFC 7807 vs RFC 9457

RFC 9457 is a maintenance revision of RFC 7807. The wire format is unchanged and fully backward compatible.