Representing problem details in HTTP APIs: an introduction to RFC 7807

Almost every API has a way of reporting problems and errors, so the consumer can understand that something went wrong and what went wrong. How you do that depends on the API style, the technology, and the specific design. Either way, error reporting is part of the design work that every team has to address.

For APIs that use the Hypertext Transfer Protocol (HTTP), some basic reporting is possible with HTTP status codes. There are around 60 status codes, and they already describe a useful range of conditions. But they are often not specific enough. Teams frequently need to add a more detailed problem type or point to a specific failed request, and the question is how to do that consistently.

The scale of the problem is why a standard matters. HTTP 429 alone accounts for almost 52% of all 4xx and 5xx API error responses, according to Cloudflare’s 2024 API Security and Management Report. Automated discovery also turns up 30.7% more API endpoints than teams self-report, a sign of how many APIs go unmanaged, per Cloudflare. Adoption keeps climbing too, with 74% of teams calling themselves API-first, up from 66% a year earlier, according to Postman’s 2024 State of the API Report. Yet 39% of developers name inconsistent documentation as their biggest obstacle with APIs, per the same survey. With that much error traffic across that many APIs, a shared format for problem details saves everyone time.

You can design your own error format, but that takes effort on your side and for every consumer who has to learn it. There is a standard for this, and this article introduces both the original specification, RFC 7807, and its 2023 successor, RFC 9457.

What is RFC 7807?

RFC 7807 is an IETF specification that defines a standard JSON format for reporting errors from HTTP APIs. Published in 2016 as Problem Details for HTTP APIs, it gives APIs a consistent way to return machine-readable error details, so you avoid inventing a new error format for every service.

The specification also defines two media types for the response body, application/problem+json and application/problem+xml, so clients know exactly how to read the payload.

By using RFC 7807, API designers save the effort of designing their own way of exposing API problem details, and API consumers can apply their understanding of that standard to all APIs where it is used.

Erik Wilde, co-author of RFC 7807 and RFC 9457

The five members of a problem details object

A problem details object is a JSON object with five standard members, all of them optional. Each one adds context that an HTTP status code alone cannot carry.

• type. A URI reference that identifies the problem type. Ideally it resolves to human-readable documentation, though that is not required. It is more specific than the status code.
• title. A short, human-readable summary of the problem type. It should stay the same for the same type.
• status. The HTTP status code, repeated here so the problem details are self-contained and can be read outside the original HTTP response.
• detail. A human-readable explanation specific to this occurrence of the problem.
• instance. A URI reference that identifies the specific occurrence of the problem.

Here is what a single problem looks like in the application/problem+json format:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "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"]
}

How problem details support extensions

Problem details use a simple extension model. An API is free to add any other members to the object, so everything beyond the five standard members is an extension. In the example above, balance and accounts are extensions. Clients must ignore members they do not recognize, which keeps the format forward-compatible.

There is no namespacing or central registry in the original specification, so the meaning of an extension is defined by the problem type, not by RFC 7807 itself. If you want more patterns and anti-patterns, this talk by Mike Amundsen walks through how he adopted RFC 7807 in real API designs.

Meet RFC 9457, the 2023 update that obsoletes RFC 7807

RFC 9457 is the 2023 successor to RFC 7807, and it now obsoletes the original specification. Published in July 2023 under the same name, Problem Details for HTTP APIs, it keeps the format almost identical, so existing implementations stay compatible. The two media types and the five standard members are unchanged.

The specification lists three headline changes in its own appendix. It clarifies how to report multiple problems, it adds an IANA registry of common problem type URIs, and it adds guidance for type URIs that cannot be dereferenced. Everything else, such as updated references to RFC 9110 for HTTP semantics, is refinement rather than a breaking change.

RFC 7807 vs RFC 9457, what changed

The main difference between RFC 7807 and RFC 9457 is not the core format but the guidance around it. The table below compares the two at a glance.

Because the members and media types did not change, a client that reads RFC 7807 responses will read RFC 9457 responses the same way.

Reporting multiple errors with the errors array

To report several problems in one response, RFC 9457 shows an errors array, where each entry describes one problem and points to the field that failed with a JSON Pointer. This is common when validating a form where more than one field is wrong.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.net/validation-error",
  "title": "Your request is not valid.",
  "errors": [
    { "detail": "must be a positive integer", "pointer": "#/age" },
    { "detail": "must be 'green', 'red' or 'blue'", "pointer": "#/profile/color" }
  ]
}

One point of accuracy that many guides miss is that the errors array is a problem-type extension, not a new standard member. RFC 9457 presents it as an example pattern rather than a required field. This approach replaces the older idea of using the 207 Multi-Status code, which did not map cleanly onto HTTP semantics.

Reusing problem types with the IANA registry

RFC 9457 adds an IANA HTTP Problem Types registry so that common, widely used problem type URIs can be shared and reused instead of reinvented per API. The registry is seeded with the about:blank type and uses a Specification Required policy for new entries. When a standard problem type already fits your case, reusing it makes your API easier for consumers to understand.

Choosing a good type URI

The type member is the primary identifier of a problem, so choosing a good URI matters. Use an absolute URI, and where you can, make it resolve to documentation that explains the problem type. When a type has no useful documentation to point to, the default value about:blank tells clients that the status code is the only classification. RFC 9457 also adds guidance for URIs that are not meant to be dereferenced, such as tag URIs, so you have a valid option when a web page is not appropriate.

Security and error-handling anti-patterns

Detailed errors help developers, but the detail member is human-readable and often reaches untrusted clients, so it must not expose internal information. Do not put stack traces, SQL fragments, internal hostnames, or secrets into a problem details response. Keep the detail specific enough to be useful and general enough to stay safe, and log the sensitive diagnostics on the server instead.

Do you need to migrate from RFC 7807 to RFC 9457?

For most teams there is no rush. RFC 9457 is backward compatible, so existing RFC 7807 responses remain valid and existing clients keep working. Adopt RFC 9457 for new API designs to benefit from the clearer guidance and the shared registry, and update older APIs when you next revise their error handling rather than as an emergency change.

Design better APIs with Axway

Consistent problem details are one part of good API design, and they pay off most when they are governed across every API in your organization. Some 78% of decision-makers do not know how many APIs they have, according to Axway’s 2024 API maturity survey. The average enterprise runs 897 applications while integrating only 29% of them, per the MuleSoft 2025 Connectivity Benchmark Report.

Amplify API Management helps you design, secure, and govern APIs consistently, so standards like problem details are applied everywhere rather than one service at a time. See also what API governance is and how it keeps design standards enforced at scale.

Frequently Asked Questions

What is RFC 7807?

RFC 7807 is an IETF specification, published in 2016, that defines a standard JSON format called problem details for reporting errors from HTTP APIs. It uses the application/problem+json media type and five members: type, title, status, detail, and instance.

What is the difference between RFC 7807 and RFC 9457?

The difference between RFC 7807 and RFC 9457 is guidance, not format. RFC 9457 keeps the same five members and media types, then adds an IANA problem type registry, clarifies how to report multiple problems with an errors array, and adds guidance for type URIs that cannot be dereferenced.

Did RFC 9457 replace RFC 7807?

Yes. RFC 9457, published in July 2023, obsoletes RFC 7807 and is the current version of Problem Details for HTTP APIs. Because it is backward compatible, existing RFC 7807 responses stay valid.

What is the application/problem+json media type?

The application/problem+json media type tells a client that the HTTP response body is a problem details object in JSON. An XML variant, application/problem+xml, is also defined for APIs that use XML.

How do you return multiple errors in a problem details response?

To return multiple errors, RFC 9457 shows an errors array where each entry describes one problem and uses a JSON Pointer to identify the field that failed. The errors array is a problem-type extension rather than a standard member.

Is RFC 9457 backward compatible, and do I need to migrate?

RFC 9457 is backward compatible with RFC 7807, so there is no urgent need to migrate. Use RFC 9457 for new API designs, and update existing APIs when you next revise their error handling.

What does the type member do?

The type member is a URI that identifies the problem type and acts as its primary identifier. If it is omitted, the default about:blank means the HTTP status code is the only classification of the problem.