skip to content

In a retail-banking web app, how should the API's error envelope map onto the transfer form's field errors, page failures, retries and expired sessions?

level: middleimportance: must knowfreq 58%

answer

  1. one envelope, one interpreter
  2. branch on status and type, not text
  3. 422 pointers land under fields
  4. 401: re-authenticate, keep the draft
  5. retry the transfer with the same key

basics

~20 s

Use one envelope everywhere, problem details with a stable type and per-field errors, and map by status and type: 422 field errors inline, 401 to re-authentication keeping the draft, 503 or a lost response to a retry, the rest to a page-level state.

solid answer

~40 s

I'd have every endpoint return the same error envelope: problem details (`application/problem+json`) with a stable `type` and, for validation, an extension listing each field error with a pointer into the request. The client maps on HTTP status plus `type`, never on the `detail` text. On the transfer form, a `422` with field errors renders inline under each named field and keeps what the user typed; a business refusal such as an exceeded daily limit becomes a form-level message. A `401` means the session expired: prompt re-authentication and keep the draft. A `503` or a lost response is retryable, and the transfer is retried only with the same idempotency key. A `403`, a `404` or an unexpected `5xx` becomes a page-level state.

code

http · 12 lines
http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://bank.example/problems/transfer-invalid",
  "title": "The transfer request is not valid.",
  "status": 422,
  "errors": [
    { "pointer": "#/amount", "detail": "must be greater than zero" },
    { "pointer": "#/destinationAccount", "detail": "is not a valid account number" }
  ]
}

go deeper

for a junior

Recall that a field error belongs under its field and that the form keeps what the user typed.

for a middle

Explain the mapping: status plus a stable type decides inline, form-level, retry, re-authenticate or page state, and why detail text is never parsed.

for a senior

Show the transfer's retry path: a lost response is not a failure, and only the same idempotency key makes a retry safe when money moves.

for a principal

Set the rule that every service speaks one envelope and the client owns the copy, and weigh it against teams' freedom to shape their own errors.

## One envelope, one interpreter If every endpoint invents its own error shape, the client needs a special case per endpoint, and the screens drift apart in how they fail. One **error envelope** for the whole API lets the client write one interpreter that turns any failure into a UI state. A ready-made envelope is **problem details** (RFC 9457, which obsoletes RFC 7807): a JSON object served as `application/problem+json` with the members `type` (a URI identifying the problem type), `title` (a short human summary), `status`, `detail` (a human explanation of this occurrence) and `instance` (a URI for this occurrence). Problem types may add **extension members**; the RFC's own example adds an `errors` list in which each entry has a `detail` and a JSON `pointer` into the request. Two rules from the RFC matter to the client: - `type` is the problem's primary identifier, so the client branches on it; - consumers should not parse `detail`, which is prose for people and may be reworded or localised. What the body should and should not contain, and how a request id reaches support, belong to the error body's own design, a neighbouring subject. This question is about what the screen does with it. ## The mapping, case by case | Situation in the banking app | HTTP status | What the client reads | UI state | |---|---|---|---| | Amount or account number invalid | `422 Unprocessable Content` | `errors[]` pointers | Message under each named field, input kept | | Business refusal (daily limit reached) | one status, as the API defines it | stable `type` | Form-level message with next step | | Payee changed since the form loaded | `409` or `412` | `type` | Reload the payee, ask to re-confirm | | Session expired | `401` | status | Re-authenticate, then return to the draft | | Not allowed (account not owned) | `403` | status | Page-level "no access", no retry | | Unknown account in the URL | `404` | status | Page-level not found | | Temporary outage | `503`, perhaps with `Retry-After` | status | Retry affordance | | Unexpected server fault | other `5xx` | `instance` for support | Page or section failure with a reference | ## The transfer form: field and form errors 1. Validate in the browser first for speed (required fields, number format), knowing the server stays the authority. 2. On a `422`, walk the `errors` list and attach each message to the field its pointer names; move focus to the first invalid field. 3. Keep everything the user typed. Clearing a payment form after a validation error is a classic defect. 4. Show a refusal that is not about one field, such as a daily limit, as a form-level message, ideally with the remaining allowance carried in an extension member. ## Session expiry is not an error page A `401` on submit means the session ended, not that the transfer failed for a business reason. The screen should prompt re-authentication without losing the draft and bring the user back to the form. Where the draft is kept while that happens is a state-placement decision; the contract's job is to make `401` distinguishable from every other failure. After re-authentication, ask the user to confirm again rather than resubmitting a money transfer silently. ## Retryable versus final - **Retryable**: a network failure, a timeout, a `503`. Reads can retry automatically with growing gaps; the transfer shows a retry action. - **Final**: most `4xx` responses, because the same request gets the same answer. - **Unknown**: a request that timed out may have been applied. The transfer is retried only with the **same idempotency key**, so the server can return the transfer it already created instead of making a second one. ## The copy belongs to the client The client maps each known `type` to its own localised message, so tone and language match the rest of the UI and a refusal can carry a useful next step. The server's `title` and `detail` remain the fallback for types the client does not yet know. A simple order of precedence keeps the interpreter small: - a known `type`: the client's own message, in the place the table above names; - an unknown `type` with a `4xx` status: the server's `title` as a form-level message, input kept; - an unknown `5xx`: a page or section failure that shows the `instance` reference for support; - no response at all: the retryable state, never a claim that nothing happened.

  • The transfer request times out and no response ever arrives. What does the screen show?
    Not 'failed': the server may have applied it. The screen shows a pending state and retries with the same idempotency key, or asks the server for the transfer recorded under that key. Either way the server answers with the one transfer it created, and the screen then shows success or the real error.
  • Why should the client hold its own message for each error type instead of displaying the server's title?
    The client owns tone, layout and language: it can phrase a daily-limit refusal with the remaining allowance and a link to raise the limit, translated with the rest of the UI. The server's `title` and `detail` stay as the fallback for types the client does not yet recognise.

  • Parsing the human-readable detail text to decide which field failed
  • Clearing the transfer form after a validation error
  • Treating an expired session as a generic something-went-wrong page
  • Retrying a timed-out transfer as a fresh POST with a new idempotency key
  • Letting each endpoint invent its own error shape for the client to special-case