How do you keep one internal failure contract when two surfaces of the same service must serialize errors in different wire formats?

A service often has to speak more than one error dialect: an externally published surface that must follow a formal error standard, and an internal surface whose consumers use a leaner in-house shape. Or one standard is being migrated to another and both must be served during the transition. The question is how much of the service that difference is allowed to touch. ## Draw the seam at rendering, not at modelling There are three layers, and the discipline is to keep them apart: 1. **Failure** - what the code raises: a typed object naming the condition, carrying a stable code and any structured detail. 2. **Failure value** - what the factory produces: the neutral, format-agnostic record of code, message, correlation id and declared detail. This is your vocabulary, not anyone's standard. 3. **Rendering** - what the surface emits: field names, nesting, media type, and any members a published standard requires. Handlers only ever touch layer one. They do not learn which surface they are serving, because if they do, the knowledge of the wire format leaks back into hundreds of call sites and the second format stops being containable. | Layer | Changes when… | Should not change when… | |---|---|---| | Failure types | New domain conditions appear | The wire standard changes | | Failure value | The contract gains a concept (say, declared detail) | A surface renames a field | | Renderer | A surface adopts a different standard | New failure types are added | ## The modelling trap The common mistake is to build the failure value in the shape of whichever standard was adopted first - its field names, its nesting, its required members. It costs nothing on day one and is indistinguishable from the neutral model. Then the second surface arrives and every renderer is a translation between two foreign shapes, plus the value model quietly forces a concept the second standard does not have. Keep the value model in your own terms and both renderings are mappings out, which is the direction that stays cheap. ## Choosing the renderer Two selection mechanisms cover most cases, and they can coexist: - **By surface.** The route group, port or deployment the request arrived on determines the renderer, resolved once at the write boundary. Predictable and easy to reason about. - **By negotiation.** The renderer is chosen from what the client asked for, falling back to the surface's default when the request expresses no preference or an unsupported one. More flexible, and it makes a migration client-driven rather than a flag day. Either way the selection happens in one place. The moment renderer choice appears inside handler code, the seam has failed. ## The part to version hardest The field names are the least valuable thing in the contract and the codes are the most valuable. A client keying on a code has embedded a meaning in its own branching logic. So: - **Codes are added, never re-pointed.** Broadening or narrowing what an existing code means breaks consumers silently, because their branch still matches. - **Retiring a code is a deprecation with a window**, not a delete, even when the wire format around it changes. - **A new surface is not licence to renumber.** Both renderings should emit the same code for the same condition, or you have two catalogues and the failure taxonomy has forked. ## The costs a lead has to own Two renderings double a test matrix: every failure class now has to be asserted twice, and the end-to-end provocation suite runs per surface. Documentation forks. On-call engineers see two shapes in the same log pipeline unless the internal log record is normalised. None of that is fatal, but it is the honest ledger, and it is the argument for the decision an interviewer is really probing: **when to refuse the second format.** A request for a second dialect because one team prefers different field names is a request to double a test matrix for aesthetics. A published external standard the organisation is obliged to follow, or a migration with real consumers on both sides, is worth it - and both are bounded, with a defined end state. ## The judgment being assessed A strong answer lands three things: the seam is at rendering and handlers never learn the format; the neutral value model is deliberately not shaped like any one standard; and the code vocabulary is the stable asset, protected more carefully than the field names around it. A weaker answer treats the question as an implementation puzzle and reaches for a second factory - which is the same drift the shared factory existed to prevent, only now at the level of the whole contract.