In a web framework, why route every violation set through one central converter instead of shaping error bodies inside each handler?

## The decision in one sentence A validation failure produces a structured set of violations; something has to turn that set into the bytes the caller reads. The question is *where* that turning happens — in each handler, in a helper the handlers remember to call, or in one component registered on the framework's error hook so that no handler is involved at all. The third arrangement is the one that holds up, because the error body is a **contract** and a contract with many authors stops being one. ## Three places it can live | Where | How it is wired | What goes wrong | |---|---|---| | Inside each handler | Handler catches or inspects the violations and builds a body | Every endpoint invents its own field names, codes and casing; new endpoints forget entirely | | In a shared helper | Handlers call one function, by convention | Works until someone does not call it; the convention is invisible to the framework and to review | | On the framework's error hook | One registered component intercepts the validation failure before any handler body runs | The shape is enforced by the framework rather than by discipline | Frameworks differ in what the hook is called and in how it is registered — some resolve a handler by the failure type, others run an outer wrapper around the whole chain — but they generally offer a place to say "when validation fails anywhere, run this". That is the seam this pattern uses. ## What the central converter does 1. **Receives** the violation set, plus enough context to know which model it came from. 2. **Translates paths** from model property names into the names the body actually uses on the wire. 3. **Resolves messages** — a key and its parameters become text, or are passed through as a stable code with parameters so the client can render its own wording. 4. **Sorts** deterministically, usually by path, so responses and tests do not depend on enumeration order. 5. **Applies a redaction policy** to rejected values, per field or per rule. 6. **Hands the result to whatever writes the service's failure body**, so the envelope stays the same as for every other failure the service produces. ## Why per-handler shaping drifts - Twelve handlers produce twelve opinions: `field` vs `name` vs `property`, `NOT_BLANK` vs `required`, camel case in one place and snake case in the next. - A thirteenth endpoint is added under time pressure and returns a bare sentence, so the client's field-highlighting code silently does nothing for it. - Renaming one key in the body becomes a twelve-file change with no compiler help. - Each handler needs its own error-path test, so the suite grows with endpoints instead of with rules. - Cross-cutting policy — redaction, a correlation identifier, a documentation link — has to be remembered twelve times. ## The costs, honestly A central converter must be **general**. Endpoint-specific wording should not live inside it, or it grows a switch over routes and becomes the thing it replaced. The escape hatch is to push the specificity back to where the rule was declared: a constraint carries its own message key, and the converter renders whatever key it is given. Rule groups let the same model carry different rule sets on different endpoints without the converter knowing anything about routes. A second cost is **distance**. The handler author no longer sees the response their endpoint produces for bad input, so the converter needs its own tests and the body needs documenting where handler authors will read it. A contract test that posts a deliberately bad body to several unrelated endpoints and asserts the same envelope shape is the cheap guard: it fails the moment someone hand-rolls a body in a handler. ## When one endpoint genuinely needs something different It happens — a legacy integration, a form that must return a flat list of sentences. Keep it inside the one converter as an explicit branch keyed on something durable (a marker on the model, a response type), not by letting that handler build its own body. One component with a documented exception is still one contract; two components are two contracts, and the second one starts drifting the day it is written. ## What good answers say That the violation set is an internal representation and the error body is a published shape; that the framework offers exactly one place where the mapping between them belongs; and that the payoff is not tidiness but **change cost** — the day the body has to gain a documentation link or a request identifier, that is one edit and one test, applied uniformly to endpoints nobody has to enumerate.