How would you decide whether exception-to-status mapping lives in one central registry or in per-module handlers across a large service?

## The two pulls **Centralise everything.** One registry, one file, every exception type in the service listed with its status. It gives perfect consistency and a single place to review the API's failure contract. It also becomes a bottleneck: every team edits it, it grows to hundreds of entries, and the transport layer ends up importing types from every corner of the domain — a dependency direction most architectures work hard to prevent elsewhere. **Distribute everything.** Each module registers handlers for its own failures. Teams move independently and nobody edits shared code. But nothing keeps two modules from mapping the same concept differently, so callers see one concept answered inconsistently, the same broad registration gets copy-pasted into five modules, and the service's failure contract exists only as the union of things nobody has read together. ## The arrangement that survives Split the decision into **vocabulary** and **membership**. - The **vocabulary** is a small closed set of failure categories — on the order of six to ten — each with exactly one status, one body shape and a written definition of when it applies. It lives centrally and changes rarely; adding a category is a deliberate review. - The **membership** is which of a module's failure types belongs to which category. That is domain knowledge, it changes constantly, and it belongs with the module. The transport layer then knows only the categories. A module contributes by making its failures carry or implement a category, or by registering a narrow local mapper that produces one. Two consequences follow: adding a failure type never touches shared code, and no module can invent a status. | Approach | Consistency | Team autonomy | Coupling | Where it breaks | |---|---|---|---|---| | One central table of every type | High | Low | Transport depends on all domains | Grows to a bottleneck file | | Fully independent per-module handlers | Low | High | Low | Same concept, different statuses | | Central categories, module membership | High | High | Modules depend on a tiny shared vocabulary | Category set must stay small | ## How to decide for a given service Weigh these, roughly in this order: 1. **How many teams touch the API surface?** One team can run a central table indefinitely; five cannot. 2. **Is the API one contract or several?** If different route groups deliberately expose different failure contracts, scoped registries per group are legitimate rather than a smell. 3. **How stable are the failure types?** Rapidly growing domains punish any design that requires a shared-file edit per new type. 4. **Who is accountable for the public contract?** Whoever must answer for "why does this return 409" should own the category set, and nothing else. 5. **What is your review capacity?** A distributed scheme only works if there is an automated check; without one it decays to independent per-module mapping within a year. ## Making the boundary real - **Keep the category set closed** and require a review to extend it — that review is the actual governance moment. - **Forbid registering on the broadest failure type outside the shared registry.** A module-scoped catch-all is how a module quietly acquires status authority. - **Test at the boundary, not the unit.** For each module, assert that its representative failures resolve to the intended category, and that nothing resolves to the generic fallback by accident. - **Alert on fallback rate.** A rising share of failures landing on the unmapped path means the membership is drifting behind the domain. - **Publish the categories as documentation**, because they are the failure half of the API contract that callers actually integrate against. ## The tradeoff to state out loud This design buys consistency and autonomy at the cost of **expressiveness**: a module that genuinely needs a status outside the vocabulary must either argue for a new category or accept the nearest one. That friction is the point — it is what stops the vocabulary from becoming the union of everyone's preferences — but it is a real cost, and in a service whose modules serve genuinely different audiences it may be the wrong trade. The honest principal answer names the conditions under which you would abandon it: few teams, one shared audience, and a stable domain make the plain central table simpler and better. What interviewers are listening for is whether you treat the mapping table as **API governance** rather than as configuration. The mechanics are easy; deciding who is allowed to say what a failure means to a caller is the part that has to be designed.