Code10x
Exception designmedium0-2 years

A service throws a single `ServiceException` for everything — not found, validation failure, and a downstream timeout all end up as the same type with different messages. What's wrong with that design, and how would you restructure the hierarchy?

A single catch-all exception type throws away the one piece of information a boundary handler actually needs: whether the request was understood and refused (the caller's fault — not found, a conflict, an invalid state) or the system genuinely failed (nobody's fault at the API level — a downstream timeout, a database outage). Those two categories map to completely different HTTP responses — 4xx versus 5xx — and need completely different handling: a not-found is a normal, expected outcome worth logging at most at INFO, while a downstream timeout is a real operational problem that needs the full stack trace at ERROR. With one flat ServiceException, the boundary handler has to parse the message string to guess which is which, which is fragile and eventually wrong. The fix is a small, deliberate hierarchy: an abstract BusinessException (with a stable, machine-readable code) for caller-fault outcomes, and a separate InfrastructureException for system failures — few types, not one per error, with the specific case carried by the code field rather than by the class.

The lesson behind it →
PreviousA method opens a database connection in a `try-with-resources` block. The body throws a business exception, and `close()` on the connection also throws (the pool rejects a broken connection). What does the caller actually catch, and where did the `close()` failure go?Next A colleague shows you code that throws a checked `IOException` straight out of a `Runnable.run()` — no wrapping, no `UncheckedIOException` — and it compiles cleanly with no error anywhere. How is that possible, and what does it prove about what "checked" actually means?
More on Exception design
A high-throughput lookup service throws `NotFoundException` for an ordinary "no such record" outcome, thousands of times a second under normal load. Profiling shows a meaningful chunk of CPU going into exception construction, not into the throw itself. What's actually expensive here, and how would you fix it without changing the exception's meaning?