A batch endpoint processes 100 items and 3 of them fail validation. How do you report that over HTTP - what does status 207 Multi-Status mean, and when would you return a plain 200 with a per-item status array instead?

## The problem HTTP's status line describes the outcome of *one* request. A batch has many outcomes. Any single code you pick is either a lie or a loss of information: - **200 OK** implies everything worked. Clients written the obvious way (`if (res.ok) markAllSynced()`) will silently drop the 3 failures. This is the most common and most damaging bug in batch integrations. - **400 Bad Request** implies nothing worked. The caller retries all 100, duplicating the 97 that succeeded. - **500** is worse still: it invites a blind retry of everything and pollutes error budgets with a request the server actually handled. So the outcome has to live in the body, per item, and the status line becomes a summary. ## 207 Multi-Status 207 comes from WebDAV (RFC 4918) and means precisely: the response body contains multiple status codes, one per sub-operation, and the recipient must inspect them. It is defined for a WebDAV XML body but the code itself is widely reused for JSON batch responses. Its value is behavioural, not decorative. A client generated from a spec, or a naive `response.ok` check, treats 207 as success in some HTTP libraries too - but it is at least unfamiliar enough to prompt someone to read the docs, and it lets dashboards and gateway rules distinguish "mixed" from "clean". Use it when your consumers are internal, or when you can be confident the documentation will actually be read. ## When plain 200 is the better contract Large public APIs frequently return 200 with a result array. The reasons are practical: unfamiliar codes trip up generated SDKs, some proxies and API gateways have opinions about non-standard 2xx codes, and observability tooling buckets them awkwardly. If your audience is broad and heterogeneous, 200 plus a rigorously documented, machine-readable result array is defensible - the per-item structure is doing the real work either way. The decision is about **client population**, not correctness purism. ## Shape of the per-item result Each entry needs: 1. **The caller's correlation id** - never rely on array position, which breaks under reordering or omission. 2. **A per-item status**, typically the HTTP code that a single-item request would have returned: 201 created, 200 updated, 409 conflict, 422 validation failure, 404 not found. Reusing the code space means callers already know the vocabulary. 3. **A machine-readable error** on failure - a stable `code` plus a human `message`, and ideally a field pointer. RFC 9457 problem details is a good per-item shape. 4. **The created resource's id or URL** on success, so the caller does not need a follow-up read. Add envelope-level counts (`succeeded`, `failed`) so operators can triage from a log line without parsing every entry. ## What genuinely deserves a whole-batch error status Distinguish *request* failures from *item* failures. The request itself is bad - and a single 4xx is correct - when the JSON is malformed (400), the item count or body size exceeds the published limit (413 or 400), authentication or authorisation fails (401/403), or rate limits are exceeded (429). In those cases nothing was attempted and the caller should retry the whole thing after fixing the request. ## Retry guidance is part of the contract A partial-failure response must let the client build the retry set: retry only the items whose per-item status is retryable (429, 503, or a documented transient code), and never retry 422 validation failures unchanged. Say this explicitly in the documentation, because the default client behaviour - retry everything or retry nothing - is wrong in both directions.