AN EXCEPTION separates the DETECTION of a problem from its HANDLING. The code that notices the problem is rarely the code that knows what to do about it, and exceptions are the mechanism for passing that decision up to whoever does. WHY NOT RETURN CODES? The classic comparison: int result = withdraw(account, amount); if (result == -1) … // insufficient funds else if (result == -2) … // account frozen · the error can be IGNORED silently — the commonest cause of corrupt state, because ignoring it compiles cleanly · the error path and the value share one return channel, so a legitimate −1 is ambiguous · every caller must check at every level, and the checking obscures the logic WITH EXCEPTIONS the failure cannot be silently discarded, and the intervening layers need no error-handling code at all. (Note that some modern languages return an explicit Result/Either type instead, which recovers the "cannot be ignored" property without unwinding the stack — a legitimate third position rather than a return to error codes.) THE THREE CATEGORIES, and the distinction that governs everything else: 1. PROGRAMMING ERRORS (bugs) — a null dereference, an index out of bounds, an illegal argument from internal code. THESE SHOULD NOT BE CAUGHT AND HANDLED. They mean the code is wrong; the correct response is to fail loudly so the bug is found and fixed. Catching them hides defects. 2. EXPECTED DOMAIN FAILURES — insufficient funds, an illegal status transition, a duplicate application, an unpaid fee. THESE ARE PART OF THE SPECIFICATION. They come from the use case extensions of ACtE0804 and belong in the method signature, because a caller must handle them. 3. ENVIRONMENTAL FAILURES — a network timeout, a full disk, a database unavailable, an external service down. THESE ARE TRANSIENT AND EXPECTED IN AGGREGATE. The response is the retry/timeout/circuit-breaker machinery of the inter-organisational topic, not a domain rule. CHECKED vs UNCHECKED (Java's distinction, and the argument generalises): CHECKED the compiler forces the caller to handle or declare it. Right for category 2 — a recoverable condition the caller must think about. UNCHECKED no compiler obligation. Right for category 1 — nobody should be handling a bug — and often used for category 3, where the handling is centralised rather than local. THE PRACTICAL CRITERION: is there something USEFUL the immediate caller could do about it? If yes, checked. If the only honest response is "abort and report", unchecked, handled once at the boundary.

1. NEVER SWALLOW AN EXCEPTION. ✗ try { save(app); } catch (Exception e) { } This is the single worst line in software. The operation failed, nobody knows, and the system continues believing it succeeded. If you genuinely intend to ignore a failure, SAY SO IN A COMMENT AND LOG IT: ✔ catch (SmsException e) { // Notification failure must not roll back an issued // licence (UC-05 ext. 7a). Logged for follow-up. log.warn("SMS notification failed for {}", licenceNo, e); } The comment cites the requirement, so the next reader knows this is a decision rather than an oversight. 2. CATCH SPECIFICALLY, NOT BROADLY. `catch (Exception e)` catches the NullPointerException from your own bug alongside the timeout you meant to handle, and treats them identically. Catch the narrowest type that matches what you can actually handle. 3. DO NOT USE EXCEPTIONS FOR CONTROL FLOW. ✗ try { return map.get(k); } catch (NotFound e) { return DEFAULT; } ✔ return map.getOrDefault(k, DEFAULT); Exceptions are expensive (stack capture) and, more importantly, they obscure the normal path. 4. FAIL FAST — validate at the boundary. Check preconditions on entry, so an invalid value is rejected where it entered rather than causing a confusing failure five layers deeper. This is the constructor validation of the earlier topic, generalised. 5. PRESERVE THE CAUSE WHEN WRAPPING. ✗ catch (SQLException e) { throw new RepositoryException("save failed"); } // the original stack trace is GONE ✔ throw new RepositoryException("save failed", e); Losing the cause turns a five-minute diagnosis into an afternoon. 6. TRANSLATE AT LAYER BOUNDARIES. The domain must not throw `SQLException` — that would make every caller depend on the persistence technology, breaking the dependency rule from ACtE0805. The repository implementation catches the technology-specific exception and throws the domain's own: catch (SQLException e) { throw new ApplicationNotFound(no, e); } 7. CLEAN UP DETERMINISTICALLY. Use the language's scoped-resource construct — try-with-resources, `using`, `with`, `defer` — rather than a finally block you might forget. A resource freed in `finally` is correct; one freed only on the success path is a leak that appears only under failure, i.e. exactly when the system is already struggling. 8. AN EXCEPTION MESSAGE MUST BE ACTIONABLE. ✗ "Invalid input" ✔ "fee 12000 exceeds the maximum 10000 for category B" Include the offending value and the constraint. The person reading it at 2 a.m. has only this string. BUT NEVER PUT SECRETS OR PERSONAL DATA IN A MESSAGE that reaches a user or a shared log — a stack trace shown to an end user is an information-disclosure defect as well as a poor experience. 9. DISTINGUISH WHAT THE USER SEES FROM WHAT IS LOGGED. the LOG gets the type, the message, the cause chain, the stack, and a correlation id the USER gets a plain explanation of what happened and what to do next, plus that correlation id so support can find the log entry THE CORRELATION ID IS THE WHOLE TRICK: it links a user's complaint to the exact log record without exposing anything.

ONE OPERATION, and the error decision at each layer. This is the synthesis of the whole section. ── DOMAIN LAYER — states the rules, knows nothing about users public Licence issue(LicenceNo no, OfficerId officer) throws NotIssuableException, SeparationOfDutiesException { assertTransition(Status.ISSUED); if (!isPaid()) throw new NotIssuableException( "application " + applicationNo + " has an unpaid fee of " + feeDue()); if (officer.equals(reviewedBy)) throw new SeparationOfDutiesException( "officer " + officer + " reviewed this application " + "and may not also issue it"); … } · CHECKED exceptions, because these are category 2 — the caller must decide · messages name the offending values · both exceptions come straight from the operation contract's preconditions ── INFRASTRUCTURE — translates technology into domain terms public Application find(String no) throws ApplicationNotFound { try { return jdbc.queryForObject(SQL, mapper, no); } catch (EmptyResultDataAccessException e) { throw new ApplicationNotFound(no, e); // translate } catch (DataAccessException e) { // Category 3: transient. Wrapped unchecked so the // domain has no obligation to know the database exists. throw new RepositoryUnavailable("looking up " + no, e); } } · the cause is preserved in both branches · the domain never sees a database exception ── APPLICATION LAYER — owns the transaction, adds nothing else @Transactional public Licence handle(String no, OfficerId officer) throws ApplicationNotFound, NotIssuableException, SeparationOfDutiesException { Application app = repository.find(no); LicenceNo licNo = pool.allocate(); Licence lic = app.issue(licNo, officer); repository.save(app); events.publish(new LicenceIssued(lic)); return lic; } · CATCHES NOTHING. Every exception propagates, and the transaction rolls back — which is exactly the desired behaviour and requires no code to achieve. · THE ABSENCE OF A try/catch HERE IS THE DESIGN DECISION. A catch block would have to decide what the user sees, and this layer does not know whether the caller is a web page, a mobile app or a batch job. ── PRESENTATION LAYER — the ONE place that maps failures to responses @ExceptionHandler(NotIssuableException.class) ResponseEntity<ApiError> onNotIssuable(NotIssuableException e) { return status(409).body( new ApiError("CANNOT_ISSUE", e.getMessage(), traceId())); } @ExceptionHandler(ApplicationNotFound.class) → 404 @ExceptionHandler(SeparationOfDutiesException.class) → 403 @ExceptionHandler(NumberPoolExhaustedException.class) { log.error("licence number pool exhausted", e); // ALERT return status(503).body(new ApiError( "TEMPORARILY_UNAVAILABLE", "Licences cannot be issued right now. " + "The administrator has been notified.", traceId())); } @ExceptionHandler(Exception.class) → 500 log.error("unhandled failure, trace {}", traceId(), e); // The user gets NO stack trace and no internal detail. return status(500).body(new ApiError( "INTERNAL_ERROR", "Something went wrong. Quote reference " + traceId() + " to support.", traceId())); READ WHAT THIS ACHIEVES: · ONE place decides HTTP status codes, so they are consistent · the domain is free of presentation concerns and the presentation is free of business rules · every failure is logged once, with a trace id, and the user receives that id and nothing sensitive · the pool-exhausted case is a 503 with an alert, not a 500 — because it is operational, and someone must act · the catch-all guarantees that an unforeseen bug produces a clean response rather than a stack trace in a browser THE PATTERN, stated generally: THROW WHERE THE PROBLEM IS DETECTED, TRANSLATE AT LAYER BOUNDARIES, AND HANDLE ONCE AT THE OUTERMOST EDGE. Intermediate layers catch nothing, which is why they stay readable. AND THE CASE THIS STRUCTURE STILL DOES NOT SOLVE — worth being honest about. UC-05 extension 4a: the payment gateway times out AFTER charging the applicant. No exception handler can fix that, because the failure is that two systems now disagree. It needs a RECONCILIATION process — the compensating action of the saga pattern from the control styles topic. SOME ERRORS ARE NOT HANDLED IN CODE AT ALL; they are handled by a business process that the software must support.