RFC 9457 / START HERE
HTTP API problem details, before the details
Problem Details for HTTP APIs
This RFC defines a common shape for describing problems in an HTTP API response. It adds understandable details alongside an HTTP error status.
The idea in one picture
An API request fails
A structured problem describes it
The client can explain the failure
A simplified picture of the idea; the chapters explain the actual mechanisms.
Why it exists
Every API inventing a different error format makes clients harder to write. Shared fields let software and people identify what went wrong.
A familiar example
An API responds to an invalid order with a problem type, a title, and an explanation the client can display or handle.
Helpful background
You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.
What you’ll learn next
Begin with chapter one, or choose a topic.
- A problem responseA JSON problem object provides machine-readable error information alongside an HTTP status.→
- Problem type identityThe type URI identifies the kind of problem, while instance identifies an occurrence.→
- Human-readable detailsTitle summarizes a problem type; detail explains a particular occurrence.→
- Extension membersProblem types can define structured members beyond the standard fields.→
- Types and safe disclosureDefine a reusable type with documentation without exposing private internals.→
This introduction explains RFC 9457 (2023). Read the original RFC ↗