API error responses with RFC 9457 (Problem Details)

What it is

RFC 9457 obsoletes RFC 7807. It describes a JSON object that a server sends as the response body for errors, with the media type application/problem+json (or application/problem+xml). The fields are: type, a URI that identifies the error class and ideally returns a description when dereferenced; if it is absent, about:blank applies. title, a short summary that is the same for every occurrence of this class. status, the HTTP status code as a number. detail, an explanation of this specific occurrence. instance, a URI that identifies this occurrence. Custom extension fields ("extension members") are explicitly allowed, for example a list of field errors for validation.

Why it matters

The status code alone is too coarse: two 409 responses can mean "version outdated" and "name already taken", and they call for different reactions. A client that can branch on type decides between retrying, reloading and giving up without parsing a message text that changes with the next version. For agents that use APIs based on their documentation, a stable, documented catalog of errors is a prerequisite for not having to guess.

How to apply

• Use one error format for all non-2xx responses, defined once in the OpenAPI description and referenced by every endpoint.
• Give each error class a stable type URI under your own domain (for example https://api.example.ch/probleme/kontingent-erschoepft) that points to a page describing its meaning, typical status and recommended reaction; the list belongs in the API documentation.
• Keep type and title stable across versions; only detail describes the individual case, and it must not echo the user's input back unchanged.
• Convey retry hints in standard headers (Retry-After); the problem object may additionally mention them.
• Return validation errors as an extension field containing a list of field path, error kind and message, so that a client can show all defects at once.
• status in the body must match the HTTP status actually sent; the RFC describes the field as advisory, so that a client knows the original status even if an intermediary has changed it.

Pitfalls

Stack traces, internal hostnames or SQL in detail. Status 200 with an error object in the body, which misleads caches and clients alike. Renaming error classes without a transition period. A type URI that points to a 404 page. Introducing the format on only some endpoints, so that clients need two parsers.