Consistent API error responses with Problem Details

What it is

RFC 9457 (which obsoletes RFC 7807) specifies the application/problem+json media type with members type (a URI identifying the problem class), title (short summary), status (the HTTP status code), detail (human-readable explanation of this occurrence) and instance (URI of the occurrence), plus arbitrary extension members.

Why it matters

Clients, including agents, branch on error classes. A stable, documented code per class ("precondition_failed", "quota_exceeded") lets them decide between retry, re-read and give up without parsing prose. The HTTP status alone is too coarse: two 409s can mean different things.

How to apply

• Use one error envelope for every non-2xx response and document it once in the OpenAPI description.
• Give each error class a stable identifier and a human message that does not echo user input.
• Carry retry information in standard headers (Retry-After) rather than only in the body.
• List field-level validation problems as an array with locations and types.

Pitfalls

Leaking stack traces or configuration in detail. Changing codes between releases without a deprecation period. Using 200 with an error body, which breaks caches and clients alike.