Error response shapes clients expect
· API Vertex reviewers
Support tickets often start with “the app said unknown error.” That usually means the HTTP status was meaningful but the body was HTML from a gateway, or JSON without a stable code field.
Always pair status with a machine-readable type
Use a string constant such as insufficient_funds that does not change when copy is edited. Document the full enum in OpenAPI components.schemas.
Separate human text from diagnostic detail
title for end users, detail for engineers, instance or correlation ID for logs. Never put stack traces in partner-facing responses.
409 vs 422 — pick semantics and stick to them
We ask teams: is the conflict about state (already shipped) or about validation (bad field)? Mixing the two across endpoints forces every SDK to special-case routes.
Include recovery hints sparingly
A retry_after field on rate limits helps. Linking to marketing pages in error JSON does not.
Book a contract workshop if product and backend still disagree on error envelopes.