API Error Design
also called Problem Details, RFC 9457
Returning failures in a consistent machine-readable structure that tells a client what went wrong, whether to retry, and what to do about it.
Error responses are where API quality is most visible and least designed. A body containing only "error occurred" forces every integrator to guess, and guessing produces the two worst behaviours: retrying something that will never succeed, and giving up on something transient.
A usable error carries a stable machine-readable code distinct from the HTTP status, since one status covers many conditions and clients must branch on the specific one; a human-readable message for logs and developers, never intended for end users; field-level detail for validation failures, so a form can highlight the right input; a correlation identifier so a support request can be traced to the exact server-side event; and retry guidance — explicitly whether this is retryable, with a Retry-After where applicable.
The status code discipline that matters most is the distinction between client fault and server fault, because it determines retry behaviour and it determines whose alerting fires. Returning 200 with an error in the body is the antipattern that defeats every generic client, proxy, cache and monitoring system at once.
The consistency requirement is organisational rather than technical: a single error shape across the whole estate means one handling implementation per client rather than one per service, and the standard Problem Details format exists so this does not have to be reinvented.