Return HTTP API failures as typed Problem Details

Use this document to connect an official requirement or behavior to observable evidence: Return HTTP API failures as typed Problem Details. Only the official source and traced locations below supply facts. Confirm applicability before acting.

Source fact:

The official RFC 9457 — Problem Details for HTTP APIs from RFC Editor / Internet Engineering Task Force supports the following bounded statements:

• A Problem Details consumer MUST use the resolved type URI as the primary problem-type identifier; when type is absent, its value is assumed to be about:blank. The research record locates this support at Section 3.1.1 (type).
• The status member is advisory, but a generator that includes it MUST give it the same status code as the actual HTTP response. The research record locates this support at Section 3.1.2 (status).
• Clients consuming Problem Details MUST ignore extension members they do not recognize so a problem type can evolve with additional information. The research record locates this support at Section 3.2 (Extension Members).

Keep the evidence boundary at these traced claims. They support a review of clients, origin services, intermediaries, caches, proxies, gateways, protocol versions, and security-policy enforcement points; they do not support conclusions outside the source’s stated conditions.

What the source does not establish

This RFC evidence supports only the named web or transport decision; it does not prove browser, intermediary, library, or service compatibility. It does not establish a deployment’s current state, authorize a production change, prove compliance, or show that DNS, certificates, identity providers, time, content delivery, network paths, and application ownership are healthy. Documented options are review inputs, not universal mandates.

Applicability questions

• For source statement 1 at Section 3.1.1 (type), which observable configuration, record, or test can confirm applicability here?
• For source statement 2 at Section 3.1.2 (status), which observable configuration, record, or test can confirm applicability here?
• For source statement 3 at Section 3.2 (Extension Members), which observable configuration, record, or test can confirm applicability here?
• What inventory proves which parts of clients, origin services, intermediaries, caches, proxies, gateways, protocol versions, and security-policy enforcement points are in and out of scope?
• Which condition in DNS, certificates, identity providers, time, content delivery, network paths, and application ownership must be healthy before evidence is trustworthy?
• What result would disprove the working assumption and return the issue to the owner?

DSE recommendation:

DSE recommends using the cited source as the evidence anchor for this decision. Anchor the review in the cited section and keep observation separate from interpretation. Record the source location, examined part of clients, origin services, intermediaries, caches, proxies, gateways, protocol versions, and security-policy enforcement points, observed and expected states, owner, and reason for deviation.

An implementation decision needs an owner, approved window, prechecks, observable outcome, stop authority, and rollback path. Validate DNS, certificates, identity providers, time, content delivery, network paths, and application ownership before and after the test, and store only sanitized operational evidence.

Verification and evidence

A reviewer should be able to retrace the decision from Section 3.1.1 (type); Section 3.1.2 (status); Section 3.2 (Extension Members) through request and response captures, negotiated protocol details, headers, cache behavior, certificate state, and server or proxy logs. Record what was collected, where, when, by whom, and which system or role it represents.

Retain the starting state, authorization, execution record, outcome, deviation, and final state as one review package. Move disruptive checks to an approved test path. Reopen the decision when versions, design, dependencies, ownership, or official guidance changes.

Official references

• RFC 9457 — Problem Details for HTTP APIs — RFC Editor / Internet Engineering Task Force