Summary

  • RFC 7807, published in March 2016, gave HTTP APIs a shared JSON and XML form for errors. The type URI was already the primary machine identifier; the HTTP status continued to serve generic HTTP software.
  • RFC 9457, published in July 2023, replaced RFC 7807. It warned that changing a type URI changes the error's identity, clarified how to handle several problems, and established a registry for common types.
  • The default about:blank type means only what the HTTP status says. The IANA registry records it alongside shared types; an API operator remains responsible for its own specific names and their durability.

A status code cannot do the whole job

Imagine a purchase request returning 403 Forbidden. The status is useful. A proxy, cache, or generic client can handle a forbidden response without knowing the shop's business. The purchasing program has a harder question. Did the account lack credit? Was the purchase blocked by a different rule? Should the customer add funds, contact support, or change the request? A bare status cannot carry every application's answer without turning the status-code registry into an inventory of businesses.

RFC 7807 was published in March 2016 to relieve that pressure. It defined a common problem-details object and the media types application/problem+json and application/problem+xml. Its example paired HTTP 403 with an out-of-credit problem, a title for people, a detail about the particular account, an instance reference for that occurrence, and extensions carrying balance and account links. The example was fictional, yet the split it demonstrated was exact: generic HTTP handling remained attached to 403; application behavior could attach to a more specific problem type.

The type member did the heavy work. RFC 7807 told consumers to use its URI string as the primary identifier of the problem. The title was advice for a human reader. The detail described one occurrence and was a poor target for parsing. A client that searched English prose for “credit” would break when the message changed or was localized. A client that recognized a type URI had a cleaner bargain with the operator. That bargain depended on the operator keeping the URI's meaning stable.

There was another address in the same response. instance identified this occurrence rather than the class of failure. Two customers could receive the same out-of-credit type and different instance identifiers. A support team might use the instance to locate a case; a program should use the type to decide what kind of case it has. Confusing the two would make every error look unique even when the same remedy applied.

The blank address that says very little

The specification also allowed a problem object with no type field. In that case the assumed value was about:blank. The name looks almost comic beside a format built for richer errors. It was a disciplined limit. about:blank says the problem has no semantics beyond its HTTP status. A 404 with that type remains a 404; the body has not silently invented a new machine-readable class.

That default draws a line around the power of a shared format. A uniform JSON envelope cannot manufacture a shared meaning. If an API wants clients to distinguish out-of-credit from a different 403, it must define a type and maintain that definition. If it has only the status-level fact to convey, about:blank keeps the claim narrow. The envelope lets an operator speak precisely; it cannot speak precisely on the operator's behalf.

Nor did the new format demote HTTP's own status. The status member inside a problem object was advisory. RFC 7807 required generators that include it to use the same code in the actual response, because general HTTP software reads the response line, not a JSON member. A copied body or an intermediary can create a discrepancy. The wire status still directs the ordinary HTTP machinery, while the body gives an application a finer account of the failure.

2023 made the address harder to treat as decoration

RFC 9457 replaced the 2016 document in July 2023. The basic bargain survived: type is the primary problem identifier, instance names an occurrence, detail is prose for that occurrence, and status is advisory. The successor sharpened what happens when a designer treats the type URI like an incidental label. It recommends absolute URIs where possible. A relative type such as example-problem can resolve to different identities under different response URLs. The same spelling then names two different problems.

The revision gives an even sharper migration example. An operator can use a non-resolvable URI as a type. If it later wants a resolvable address so tools can retrieve documentation, switching to a new URI changes the type's identity and can break clients. The origin may control its name, yet control is not freedom from the contracts already made with users of that name. A neat error object can thus create long-lived maintenance work for a team that thought it was merely formatting a response.

RFC 9457 also clarifies that when unrelated problems occur together, a response should present the most relevant or urgent one. A validation problem can contain an errors extension with several field-specific failures of the same type. Throwing several unrelated types into a generic bag fits HTTP's single response status poorly. The distinction is practical: a client needs to know which condition governs this response before it can decide what to do next.

The successor created the IANA HTTP Problem Types registry for common, widely used names. Its registration policy is Specification Required, and the document excludes vendor-specific, application-specific, and deployment-specific entries. The registry gives shared problems a public place; it does not absorb every shop's out-of-credit rule. The protocol community standardized a grammar and a small common vocabulary, then left specific promises with the people who publish specific APIs.

An error name is a maintenance obligation

The historical shift was modest in syntax and large in accountability. Before 2016, an API could define its own error document or overload a status code with private meaning. After RFC 7807, it could use a familiar envelope while assigning a durable URI to the failure its clients needed to recognize. The 2023 revision put the long-term cost of that decision in plain view: move the address and the machine identity moves with it.

The standards themselves do not count deployed clients. Dated server responses and client releases would establish who used the format and when. The records do establish the design bargain. HTTP keeps the broad verdict. A type URI carries the application's sharper one. The operator who mints that URI owns the promise that it will still mean the same thing when a client reads it tomorrow.