skip to content

In a retail-banking web app, the offers service behind the accounts overview is down; what should the overview's API response carry, and what should the screen render?

level: seniorimportance: should knowfreq 43%

answer

  1. fails in parts, report in parts
  2. a status per section, not per response
  3. unknown is not empty
  4. balances essential, offers optional
  5. GraphQL: nullable where failure stops

basics

~20 s

Return the overview with balances and cards, and mark the offers section unavailable and retryable, rather than failing the whole response or sending an empty list. The screen renders what arrived and degrades the offers slot; a balances failure justifies a page-level error.

solid answer

~40 s

The overview is one response composed from three sources, so its envelope needs a status per section. With offers down, I'd return `200` with balances and cards as normal and `offers` as `{ "status": "unavailable", "retryable": true }`: not a `503` for the whole screen, and not `offers: []`, which says "you have no offers" when the truth is "unknown". The composer bounds each upstream wait so slow offers cannot delay balances. The screen renders balances and cards, and the offers slot shows a quiet placeholder or hides, because offers are optional. Sections are not equal: if balances fail, the overview has lost its purpose, so that becomes a page-level error. With GraphQL the same design works only if `offers` is nullable, because a null in a non-null field propagates to its parent.

code

json · 11 lines
json
{
  "balances": {
    "status": "ok",
    "data": [ { "accountId": "acc_1", "available": { "value": "1250.40", "currency": "EUR" } } ]
  },
  "cards": {
    "status": "ok",
    "data": [ { "cardId": "card_9", "last4": "4821", "state": "active" } ]
  },
  "offers": { "status": "unavailable", "retryable": true }
}

go deeper

for a junior

Recall that one failed source should not blank the whole screen when the rest of the data arrived.

for a middle

Explain a per-section status in the envelope, and why an empty list is the wrong signal for a section that could not be loaded.

for a senior

Classify sections as essential or optional, bound each upstream wait, and show how GraphQL nullability decides where a failure stops.

for a principal

Set the house rule for every fan-in screen, a status per section with essential sections named in the design, and own its cost against simpler all-or-nothing responses.

## A fan-in screen fails in parts The accounts overview of a **retail-banking web app** is a **fan-in** screen: one view built from three back-end services (balances, cards, offers), composed into one response by the API or by a backend-for-frontend. Three sources mean three independent ways to fail, and most of the time only one of them is failing. The contract must let the screen tell "this part is missing" apart from "everything is broken" and from "there is nothing here". ## Three responses that get it wrong | Response when offers is down | What the screen concludes | Why it is wrong | |---|---|---| | `503` for the whole overview | Nothing loaded | Balances and cards were fine and are thrown away | | `200` with `offers: []` | The user has no offers | The truth is "unknown", and the screen cannot offer a retry | | Held until offers recovers | Still loading | The essential sections wait on the least important one | Each of these is a real choice a team makes by default: the first because a dependency failed, the second because an empty list "renders fine", the third because the response "should be complete". ## A status per section The fix is to give every section of the composed response its own status, as in the example: `status` of `ok` with the section's data, or `unavailable` with a `retryable` flag. The overall response is `200`, because the overview request itself succeeded. The client then renders section by section: - **ok**: render the data; - **unavailable and retryable**: render the section's degraded state and try again later; - **unavailable and not retryable**: render the degraded state only. An empty list and an unavailable section now mean different things on the wire, so the screen can say "no offers right now" only when that is true. ## Not every section is equal Which failures are local and which are fatal is a product decision made in the design, not in the error handler: | Section | Essential to the screen? | UI when it fails | |---|---|---| | Balances | Yes, the reason the user opened the page | Page-level error with retry | | Cards | Partly; a user checking a card's state needs it | Section message with retry | | Offers | No | Hide the slot or show a quiet placeholder | Showing last known balances with a timestamp instead of an error is a caching decision with its own trade-offs; reporting each section failure so someone notices is a telemetry decision. Both sit beside this one. ## Time is a failure too A slow service can hurt as much as a dead one. The composer should: 1. call the three services in parallel; 2. give each its own timeout, derived from the overview's load budget; 3. on timeout, mark that section unavailable and retryable and send the rest. Without step 2, the response time of the whole overview is the response time of its slowest dependency. ## The same design in GraphQL GraphQL has partial results built in. When a field's resolver fails, the specification treats it as returning null and adds an entry to the response's `errors` list, with a `path` to the field, while the rest of `data` is returned: a **partial response**. The catch is nullability: - if `offers` is **nullable**, the null stops there and balances and cards render; - if `offers` is **non-null**, the null propagates to the nearest nullable parent, perhaps the whole overview field; - if every field from the root down to the failure is non-null, the `data` entry itself is null. So per-section failure in GraphQL is a schema decision: sections that may fail independently must be nullable. ## What the screen shows - Each section reserves its space while loading, so a late or failed section does not shift the balances the user is reading. - A degraded section says what is missing in plain words ("Offers are unavailable right now") rather than an error code. - A retryable section offers a retry action of its own, scoped to that section, instead of reloading the page. - The page-level error is kept for the one case the design names as fatal: no balances.

  • Should the offers section retry on its own, and how often?
    Once or twice with growing gaps is reasonable for an optional section that is marked retryable; after that it stays in its placeholder until the user returns to the page. Retrying hard from every open overview adds load to a struggling service, and offers are not worth that.
  • In a GraphQL overview, what happens if `offers` is declared non-null and its resolver fails?
    The null cannot stay on `offers`, so it propagates to the nearest nullable parent, perhaps the whole overview field; if every field up to the root is non-null, `data` itself is null. The error is still listed in `errors` with its path, but the screen loses balances and cards too. Nullable section fields let the failure stop at the section.

An airport departures board shows one flight as 'delayed, check later' instead of going blank when that airline's feed fails; travellers on every other flight still read their gate.

  • Returning 503 for the whole overview because one of three sources failed
  • Sending offers as an empty list when the offers service is down
  • Holding the response until the slow service answers so it arrives complete
  • Making every overview field non-null in GraphQL and expecting per-section errors
  • Showing the same page-level error whichever section failed