API Error Contract
An API error contract standardizes the error response shape — code, message, details, trace ID — so the client can programmatically branch on the code and the operator can trace the instance.
Definition
An API error contract is the specification of the error response structure — a stable error code the client branches on, a human message, a details object for field-level errors, and a trace ID for correlation — so that the client handles errors programmatically rather than parsing prose and the operator traces any error instance to its source.
Context and scope
Applied in every API, where the error response is part of the contract and the client must handle it without a human reading the message.
Common misconceptions
- HTTP status codes are the error contract — they are the top-level signal; the error code and details are the contract within the body, which the status alone cannot express
- A generic error shape is sufficient — a generic shape is a start; the error codes and the field-level details are the contract, and a generic shape without them is just a wrapper
Anti-patterns
- Returning a 500 with a prose message for a validation error, so the client cannot distinguish a client error from a server fault
- Changing the error code for an existing condition, so clients that branch on the code break on the rename
Related concepts
Authoritative source
What it is
An API error contract is the specification of the error response structure — a stable error code the client branches on, a human message, a details object for field-level errors, and a trace ID for correlation — so that the client handles errors programmatically rather than parsing prose and the operator traces any error instance to its source. Applied in every API, where the error response is part of the contract and the client must handle it without a human reading the message. An API is a contract, and a contract’s value is the stability that lets clients and servers evolve independently — breaking the contract breaks the clients you do not control.
How it works
Versioning makes change explicit: a new field is additive, a removed or retyped field is breaking, and the client must be able to ignore what it does not understand. Pagination, filtering, and error formats are part of the contract, not afterthoughts. Documentation is generated from the schema so it cannot drift. Deprecation gives clients a runway, marked in headers and logs, before the removal.
When to apply and pitfalls
Apply whenever more than one client consumes the interface. The pitfall is treating the API as the implementation’s reflection — changing the URL because the internal class changed, exposing database columns as fields. Another is versioning by URL path and accumulating N parallel codebases rather than versioning by capability and evolving one.