Require that our 4xx client-error responses define a schema, ideally a consistent error object with a code, a message, and enough detail for a consumer to understand what went wrong and how to fix it. I have integrated with APIs whose errors were free-form strings that changed shape from one endpoint to the next, and building reliable handling on top of that is miserable. A defined error schema, applied uniformly across the surface, lets consumers parse failures programmatically and lets us evolve error messaging without breaking anyone. Standardized, well-described errors are one of the clearest signals of a mature API.
4xx Response Schema (OpenAPI)
Strategies
API Responses Must Be Meaningful and Consistent
All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers...
Experiences
Contracts
Every API is a contract, and the contract experience is about how clearly the promises between provider and consumer are expressed. Technical contracts like OpenAPI and AsyncAPI describe what the A...
Consistency
Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as var...
Reliability
If an API isn’t reliable, consumers will eventually look for alternatives. Reliability starts with the platform and infrastructure where the API is deployed, but it also depends heavily on the pace...
Lifecycle
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
