In a batched GraphQL request, what does the single HTTP status code tell you about each operation?

## One status line, many independent outcomes HTTP gives a response exactly one status code. Batching puts many GraphQL operations behind one response, so the status has to describe something they share, and the only thing they share is the HTTP request itself: was the body readable, was it within limits, did authentication succeed, did the server manage to produce a reply at all. It cannot describe outcomes that differ between members, and in a batch they routinely do. What servers actually do, by convention, is answer 200 as soon as they can produce the response array, whatever happened inside it. A batch of three against a charity donations graph might come back like this: ```json [ { "data": { "campaign": { "title": "Winter Appeal", "raisedPence": 1830450 } } }, { "errors": [ { "message": "Cannot query field 'giftAidEligible' on type 'Donation'.", "locations": [ { "line": 1, "column": 34 } ] } ] }, { "data": { "donor": null }, "errors": [ { "message": "Donor lookup timed out", "path": [ "donor" ] } ] } ] ``` One 200. Inside it: a clean success, a document that never executed because it failed validation, and an operation that executed and hit a failure partway through. Anything reading only the status sees a healthy request. ## Two scopes of failure, and only one of them is in the array The distinction worth being precise about is **whole-request** failure versus **per-member** failure. A whole-request failure happens before or outside member execution: the body is not valid JSON, the array exceeds the server's member cap, the content type is unsupported, credentials are missing, the server is overloaded. There is no array to return, so the server answers with a single result envelope or a plain error body - a map, not an array - and it may well use a 4xx or 5xx status, because now the status genuinely does describe the whole thing. A per-member failure is contained. The member's own envelope carries it. A validation failure produces `errors` with no `data` key, because the operation never ran. A failure during execution produces `data` with a hole in it alongside `errors`. Either way, neighbouring members are unaffected and keep their data. This is why a batching client cannot write `results[k]` without first checking that the parsed body is an array of the expected length. The failure mode of assuming an array - reading index 0 of an error map and getting `undefined` - produces a confusing client-side crash that hides a perfectly clear server error message. ## What this does to the newer response media type The GraphQL over HTTP working draft introduces a response media type under which a **request error** - a document that failed to parse or validate - may be reported with a 4xx status rather than the traditional 200-with-errors. That mapping is defined for a single operation, where one status can describe one outcome. A batch breaks the premise: if member 2 failed validation and members 1 and 3 succeeded, there is no status that is truthful for all three. Since the array body is not part of that specification either, the question simply is not answered by it, and servers fall back on 200 with per-member errors. If you are asked how batching interacts with status-code semantics, that is the honest answer: it does not, because batching is outside the document that defines them. ## The client contract that falls out of it A batching client library ends up owning a demultiplexing contract with several obligations, none of which the transport helps with: ```pseudocode send(members): response = httpPost(endpoint, encodeJson(members)) if not response.isSuccessStatus: failEveryPendingCaller(transportError(response.status)) # whole-request scope return body = parseJson(response.body) if not isArray(body) or length(body) != length(members): failEveryPendingCaller(protocolError("batch response shape")) return for k in 0 .. length(members) - 1: deliver(pendingCaller[k], body[k]) # each caller inspects its own data/errors ``` Three obligations show up there. First, a non-success status fails *every* caller in the batch, including the eight whose operations would have been fine on their own - the blast radius of a transport failure is the whole batch. Second, a length mismatch must be treated as a protocol error rather than quietly delivering results to the wrong callers. Third, each caller still has to inspect its own envelope for `errors`, exactly as it would have on an unbatched request. ## Why this bites in practice The most common real-world symptom is a monitoring illusion: an availability dashboard built on HTTP status shows a flat 100% while a specific operation in the batch has been failing validation since a deploy. Nothing at the transport layer is wrong, so nothing at the transport layer reports it. Detecting per-member failures means looking inside the array, either in the server as it builds the response or in the client as it demultiplexes - and it means the alerting story for a batched endpoint has to be designed rather than inherited.