Errors a client can actually act on

The idea

When your API says no, something on the other end has to decide what to do next — usually a piece of code at 3am, not a person. That code can only ask three things: is this my fault, should I try again, and what exactly do I change?

Every field in an error body exists to answer one of those three questions. If a response answers none of them, the client is left with two bad moves: hammer you with retries, or throw the work away. Both look like your outage.

The same bug, three error designs

One batch of four invoices. Invoice 3 has a negative amount. Watch what a simulated client can do with each response.

POST /v1/invoices/batch   idempotency-key: bk_77a
  [0] acme        amount_cents:   1200
  [1] borden      amount_cents:    850
  [2] cinder      amount_cents:  -1200   <- invalid
  [3] dovetail    amount_cents:    430

500 Internal Server Error
{ "error": "Internal server error",
  "request_id": "req_8f21" }

400 Bad Request
{ "title": "Invalid batch",
  "detail": "One or more invoices are invalid." }

207 Multi-Status
{ "results": [
  { "index": 0, "status": 201, "id": "inv_a1f" },
  { "index": 1, "status": 201, "id": "inv_b2c" },
  { "index": 2, "status": 422, "error": {
      "code": "amount_must_be_positive",
      "pointer": "/items/2/amount_cents",
      "detail": "must be > 0, got -1200",
      "retryable": false } },
  { "index": 3, "status": 201, "id": "inv_d4e" } ],
  "request_id": "req_3c07" }

How it works

Design the body backwards from the client's decision tree. Three questions, three parts of the response — and each part is machine-readable before it is human-readable.

question              answered by                          in design c
whose fault?          status class (4xx caller / 5xx us)    422 -> mine
should i retry?       explicit "retryable" + Retry-After    false -> no
what do i fix?        stable "code" + "pointer" + detail    /items/2/amount_cents

The status code is the cheap signal every generic HTTP client already reads; the body is where the specifics live. Never let them disagree. A validation failure returned as 500 tells the client's retry layer "transient, back off and try again" while the truth is "this will fail identically forever".

Why the batch arithmetic matters

Here is what the simulation actually counted, with the server writing valid rows before it hits the bad one:

design a — opaque 500, client retries with backoff
  attempts            = 1 initial + 5 retries      = 6
  rows written        = 6 attempts x 3 valid items = 18
  intended rows       =                              3
  duplicate rows      = 18 - 3                     = 15
  confirmed to client =                              0

design b — flat 400, client correctly stops
  requests = 1   rows = 0   duplicates = 0   humans paged = 1

design c — per-item results
  call 1: 3 x 201, 1 x 422 (retryable:false)
  call 2: corrected item [2] -> 201
  requests = 2   rows = 4   duplicates = 0   humans paged = 0

Design a is worse than doing nothing: it silently manufactured fifteen duplicate invoices while reporting total failure. That gap between "what the client believes" and "what the database holds" is the real cost of a vague error.

Field-level detail that a client can apply

A pointer is only useful if it addresses the request the client actually sent. Use a JSON Pointer (RFC 6901) into the request body, keep the array index, and pair it with a stable code that you promise never to repurpose. Prose is for humans and may change freely; code is an API surface.

The two kinds of "not found"

• The route doesn't exist — the caller's URL or version is wrong. That is a code bug: never retry, fix the path. Give it its own code, e.g. unknown_endpoint.
• The resource doesn't exist — the route is fine, the id is stale. The fix is data, not code: re-sync or drop the local reference. Code invoice_not_found.
• It exists, but not for you — return the identical 404, byte for byte, that a genuinely missing id returns. A 403 here confirms the resource exists, which is a real enumeration leak. Reserve 403 for callers who can already see the object and merely lack one permission on it.

You still need to debug it, so keep the distinction where it belongs: log reason=forbidden against the request_id you echoed in the body, and let support join the two.

When to use it

Note that 207 Multi-Status comes from WebDAV; plenty of teams use a plain 200 with the same results array. Either is defensible — being consistent and documented is what matters.

Watch out for

• 5xx for a caller's bad data. It invites infinite retries of something that can never succeed, and it hides the fix. The mirror mistake is just as bad: a 400 during your own outage stops clients retrying at the exact moment they should back off.
• Partial success with no index or id. If the client can't tell which items landed, it must either drop everything (lost work) or replay everything (duplicates). Return the index and the created id for every success.
• Pointers that don't match the request. "field": "amount" when the body had items[2].amount_cents forces a human to guess the mapping. Point at the exact path the caller sent.
• Retryability left implicit. Two 429s are not the same thing: "slow down for 2 seconds" and "your monthly quota is gone until the 1st" need very different client behaviour. Ship an explicit boolean plus Retry-After.
• A prose message as the only machine signal. Someone will regex your detail string, and your next copy edit will be their outage. Give them a stable code so the prose stays free.
• 403 versus 404 asymmetry. Different status, body length, or response time between "no such object" and "not yours" lets an attacker enumerate your ids without ever being authorised.

Worked example

You're reviewing a payroll import endpoint: POST /v1/timesheets/batch, up to 500 rows. Today it validates rows in a loop, and on the first bad one it throws — the framework maps that to 500, after the earlier rows have already been committed. The customer's integration retries on 5xx, six times, with backoff.

In review you'd name the three symptoms concretely: the status lies about whose fault it is, the retry is guaranteed to fail identically, and because the writes were not atomic each attempt re-created the same valid rows — six attempts over three good rows is fifteen duplicates, and the client still believes nothing was saved.

The change is small. Process each row independently and return 207 with one result per index: 201 plus the created id for successes, and for row 47 a 422 carrying code: "rate_out_of_range", pointer: "/items/47/hourly_rate", retryable: false. Keep the envelope-level 4xx for things that make the whole call unacceptable — malformed JSON, missing auth, more than 500 items — and reserve 500 for the cases where retrying really is the right advice. Add an Idempotency-Key on the batch so even a mistaken replay can't duplicate. Now the client's recovery is two lines: keep the successes, fix row 47, resend one item.

Check yourself