An error response is part of the API contract a developer has to integrate. A generic failure message can leave the customer guessing whether to fix input, wait or investigate an uncertain outcome.
Quick answer: Explain the failure class, relevant invalid field or operating condition, request reference and supported next step. Keep machine-readable classification separate from prose that may change. Avoid exposing credentials or internal implementation details, and do not imply that every failure can be safely retried.
Design for the next decision
For an illustrative conversion API, an unsupported input format needs a different next step from a temporary dependency failure. A timeout after submission may leave the outcome unknown.
| Error information | Developer decision |
|---|---|
| Stable classification | Choose the appropriate handling branch |
| Relevant field or condition | Correct a request when possible |
| Request reference | Support an authorized investigation |
| Outcome status | Distinguish rejection from uncertain completion |
| Recovery guidance | Decide whether another attempt is appropriate |
This is a proposed design checklist, not an actual provider's response schema.
Use an appropriate representation
RFC 9457 defines a problem-details model for HTTP APIs. It can be useful when designing an interface, but linking the specification does not establish that a particular API implements it.
Keep the selected product's documented contract authoritative for its actual error semantics.
Avoid a dangerous retry promise
If an operation changes state, another request may duplicate work unless the contract establishes appropriate replay behavior.
Do not turn “we did not receive a response” into “nothing happened.” Give the client an honest route to establish the outcome.
Verify the error experience
Use a controlled invalid request and inspect whether a new developer can identify the issue and next step. Label any synthetic response clearly.
The usage-limit guide and uncertain-error guide provide useful boundaries around recovery.
I'm Shashank Agarwal, creator of API.market and founder and CEO of Noveum AI. Follow my work on LinkedIn. Drafted with AI assistance.
Top comments (0)