Require that every 4xx client-error response declares its media type, so consumers know whether an error comes back as application/json, application/problem+json, or something else entirely. I have hit APIs that returned tidy JSON on success and a wall of HTML on a 400, and code that tries to parse both ends up fragile and defensive for no good reason. When error responses use a declared, consistent media type, consumers can deserialize failures the same way they handle successes and react intelligently. Errors deserve the same content discipline as everything else, and I expect that stated in the contract.
4xx Response Media Types (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
Interoperability
Interoperability is the experience of APIs, systems, and data working together without heroic effort. It is built on shared standards, common schema, and predictable contracts that let one system t...
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...
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...
