How granular should a module's custom exception subclasses be?

### Count the handlers, not the failures Every exception class you export is a question you are asking callers: *do you want to treat this case specially?* If no realistic caller would answer yes, the class is overhead — one more name in the API, one more thing to document, one more import. So the design rule is short: **a class per decision, a field per detail.** Before adding a subclass, write the handler that would catch it. If that handler does something different from the handler for its sibling, the subclass is real. If it does the same thing and only logs a different word, the difference is data. ### A worked example: the warehouse pick-list builder A pick-list builder turns an order into a sequence of aisle locations, calling an inventory service per line. It can fail in a dozen ways, but callers only make three decisions: **skip this line and carry on**, **retry the call**, or **abandon the run**. That is the shape of the hierarchy, whatever the internal failure catalogue looks like. A first version shipped with exactly one type, `PickListError`, and every failure raised it with a different message. Callers did the only thing a single type allows: `except PickListError: continue`. That handler was correct for a missing SKU and wrong for everything else, and because a timeout also unwound the block that released the run's reservation handle, every swallowed timeout left a reservation unclosed. Nothing showed up in normal operation. It surfaced after a deploy, when a 45-second cold start on the inventory dependency made timeouts common for the first minute of every restart and the handle pool ran dry. The bug was not the missing cleanup alone; it was a taxonomy that gave callers no way to tell "skip it" from "this call never happened". The fix was two intermediate classes, not twenty leaf ones: ```python class PickListError(Exception): ... class TransientPickError(PickListError): ... class PermanentPickError(PickListError): ... ``` Every concrete error derives from one branch. A caller writes `except TransientPickError: retry()` and `except PermanentPickError: skip_line()` and is still correct next quarter when three new leaf types appear, because new leaves join an existing branch. ### The other failure mode: too many classes Over-slicing is quieter but just as real. A module with one exception class per `raise` statement — twenty-three of them, named after the internal function that raised — produces an API nobody can hold in their head, so callers catch the base class and branch on nothing. Worse, those names encode your implementation: rename the internal step and either the class name lies or you break every handler. Symptoms: classes that differ only in message wording, classes that appear in exactly one `raise` and no `except` anywhere in the organisation, and documentation that lists error types alphabetically because there is no structure to present. ### Where the long tail goes Real systems have a long tail of variants that nobody branches on but everybody wants to see: a reason code, a field name, an upstream status. Put those on the instance — an attribute, ideally an enum member — rather than minting a class each. Codes scale to hundreds of values, are easy to aggregate in logs and dashboards, and can be added without touching the class tree. Their weakness is that they do not compose with `except`, which is exactly why the handful of decisions stay as classes. ### Two more levers worth knowing **Inherit a built-in where the meaning genuinely matches** — a lookup failure that is also a `KeyError`, a bad argument that is also a `ValueError` — so callers who never read your docs still catch the right thing. Do not do it to broaden the net; you inherit the built-in's promise too. **Keep the base abstract by convention.** Raising the base directly is a smell: it means a failure mode was never classified, and callers cannot discriminate. If you find yourself doing it, that is the signal that a new decision — and therefore a new subclass — exists. ### How to talk about it in an interview Start from the handler, not from the failure list. Say out loud that the hierarchy is public API: adding a leaf under an existing branch is safe, adding a top-level sibling is a change every broad handler misses, and renaming anything is a break. That framing — decisions, branches, and the compatibility cost of moving a class in the tree — is what separates a senior answer from a list of error names.