How do you keep error response bodies consistent across every endpoint of an HTTP API — and across many services in one organisation — and what concretely breaks when they are inconsistent?

## Why inconsistency happens Nobody designs three error shapes on purpose. They accumulate: the original endpoints return `{error: "..."}`; a later team adopts `{code, message}`; a third adopts `application/problem+json`; the framework's default handler produces a fourth shape for unhandled paths; and the gateway emits a fifth (often HTML) for 502s and request-size rejections. Each is locally reasonable and the aggregate is unusable. ## Concrete damage - **Client complexity.** A client cannot write one error parser. It ends up with try/guess logic — look for `code`, else `error`, else `detail`, else give up — and the give-up branch renders a useless generic message, so real, actionable failures become invisible to users. - **Broken observability.** Dashboards and alerts want to group by error code. If the field is `code` here, `errorCode` there, and absent in gateway responses, aggregation silently under-counts, and the failures that don't parse are exactly the ones from the least-maintained paths. - **Silent breakage on growth.** A new endpoint that returns a different shape doesn't fail any test — it fails at the client, in production, often as a null-dereference rather than a clean error path. - **Support cost.** No correlation id in some shapes means some tickets are simply untraceable. - **Retry logic degradation.** If retryability is expressed inconsistently, clients fall back to retrying on status alone, retrying things that will never succeed. ## Enforcement layers **Application.** One global exception handler that maps known exceptions to codes and everything else to a generic 500 in the standard envelope. The rule is: no controller constructs an error body by hand. This also closes the trace-leak hole, since nothing falls through to a framework default page. **Organisation.** Put the envelope in a shared library or service template so adoption is the path of least resistance. Documentation alone does not survive team growth. Adopting a standard media type — `application/problem+json` — helps here because it removes the design argument and gives generated clients something to key on. **Edge.** The responses your application never generates are the ones that break clients hardest. Configure the gateway or reverse proxy to emit the same JSON envelope for its own errors: upstream timeouts, unavailable backends, oversized bodies, rejected TLS or auth at the edge. Many teams discover these only when a client reports "the error page is HTML". **Tests.** Assert the shape, not just the status: a shared test helper that every service uses to validate error responses, plus API-spec linting that rejects an operation documenting an error response with a different schema. If you generate clients from the spec, this becomes near-automatic. ## What consistency should *not* mean Uniform shape does not mean uniform content. The envelope is fixed; the code vocabulary is per-domain, and structured extras (which field failed, which limit was hit) live in a well-known extension slot. Over-standardising the *values* leads to a generic code set that discriminates nothing. ## Migrating an inconsistent estate Don't attempt a big-bang rewrite. Practical sequence: pick the target envelope; make new endpoints emit it; add the gateway normalisation (largest win per unit of effort, since it covers all services at once); then convert existing endpoints, publishing both shapes only where a client genuinely cannot be updated. Track coverage as a number, because "we standardised errors" is otherwise unfalsifiable.