Errors are where API design quality is most visible and least attended to. Every provider polishes the happy path; the consumer spends most of their integration time in the unhappy one.
Start with the status code and mean it. 400 for a malformed request, 401 for missing or invalid credentials, 403 for authenticated-but-not-permitted, 404 for not found, 409 for a state conflict, 422 for semantically invalid content, 429 for rate limiting, 5xx only when it is genuinely your fault. Returning 200 with an error inside the body is the single most consumer-hostile thing an HTTP API can do, because it defeats every generic client, retry policy and monitor in the stack.
Then use one error schema across the entire API. One shape, every endpoint, every service. RFC 9457 problem details is a perfectly good off-the-shelf answer if you do not want to invent one. Include a stable machine-readable code, a human-readable message, and — where relevant — which field was wrong and what would have been valid.
Give the consumer something actionable. “Invalid request” tells them nothing. “field currency must be
a three-letter ISO 4217 code; received dollars” ends the support ticket before it is opened.
Finally, document the errors in your OpenAPI, not just the 200s. Either the provider does this work, or every one of your consumers will have to do it themselves by trial and error.
