10. Chapter review

PARTIAL_SUCCESS. The user's input was correct (geocoding confirmed it), so making them retype the city would be unhelpful and would probably fail in the same way. The display layer can show the resolved location and explain that current conditions are temporarily unavailable, which gives the user the right next action: try again in a moment, not retype London.

Earlier in the book, Chapter 7 introduced a reusable APIClient base class: it put retry, timeout, and common HTTP handling behind a private _make_request method and returned (success, data, message) tuples. Chapter 9 then rebuilt that idea around explicit error categories. Chapter 13 needs the Chapter 9 shape because the orchestrator needs the failure category as a first-class field on the result so it can distinguish transient from not_found from user_input without parsing strings. Subclassing would either force string-matching on the message tuple or override _make_request wholesale. Building a sibling client whose APIResult carries categorised context is cleaner.

The line follows whether downstream layers can act on the result. Layer 1 raises on a missing required section because nothing else can run without it. Layer 2 raises on a required field that fails type or range. A missing temperature isn't a degraded reading; it's a broken response. Optional fields (visibility, wind speed, wind direction) and Layer 3's cross-field oddities accumulate in validation_warnings and lower the quality score, which the orchestrator surfaces as warnings without changing the result status. The rule isn't "never raise"; it's "raise only when the next layer can't continue."

Different shape of problem. Chapter 11 hit three independent news APIs, normalised three different response formats into one canonical model, and merged results while letting any single source fail. Chapter 13 makes sequential calls to one provider, where weather depends on geocoding having succeeded. There's no aggregation, no canonical model to design across sources, no inter-source deduplication. Reusing Chapter 11's pattern here would add coordination overhead the workflow doesn't need.

Speed, reliability, and control. Mocking lets these tests run in seconds, never fail because someone else's API is down, and exercise specific scenarios (a 503 response, a malformed payload, a slow response) that you can't reliably trigger against a live service. The real-network case still gets covered, but at the top of the pyramid, in the end-to-end tier, where its slowness is acceptable because there are only a few of them.

Because then the orchestrator would be untestable without a network. By delegating every outbound request to the API client, the orchestrator's tests can replace the client with a mock and verify the sequencing, the partial-success logic, and the failure handling without touching the network. It's the same reason the orchestrator doesn't validate field types itself: single-responsibility per layer is what makes each layer independently testable.

What happened (a one-line description of the failure), what to do (a concrete next action the user can take), and an example (a worked instance of the suggested fix). Skip "what to do" and the user is informed but stuck. Skip "an example" and the suggestion is abstract. All three together turn a failure into something the user can act on without contacting support.