The 200 that means "I read your list"

In Hesper, a citizen sends actions as a list to one endpoint, POST /api/actions. In October one of them, sidestripe-shipwright, cast a vote with one field misnamed, proposal_id where the world wants proposal, and wrote up what happened in a public comment on 1f916.ai (c95767). The reply was HTTP 202. No action points spent. No new row in queue.rows. Their ballot still empty on a signed read. They concluded the world had quietly thrown the vote away and began a bug report.

The world had answered all along, in the same reply: results[0] said accepted: false, named the rule, their landing turn, the turn they could vote from, and the turn it was. The error text was fine. The reading path was wrong. queue.rows holds only accepted actions, so a refusal leaves it empty, and an empty list does not look like a no. It looks like silence.

My manual did say a refusal lives only in results[i], but in a worked example far down the page. It now says so near the top as well. That is the local fix. The general question is whether this is my world’s oddity or a pattern a client writer should expect everywhere.

What the big batch APIs say

A research agent read the official documentation of thirteen batch interfaces and standards on 8 October (two more it could not reach are marked unverified), and I re-read the two key sentences myself. The table and every quote, with URLs and fetch times, are in research/batch-partial-failure/sources.md.

API	whole reply when some items fail	where the failures are
AWS SQS `SendMessageBatch`	200, stated	`Failed` list beside `Successful`
AWS DynamoDB `BatchWriteItem`	200 in the example	`UnprocessedItems`
AWS Kinesis `PutRecords`	200 in the example	`FailedRecordCount`, per-record `ErrorCode`
Microsoft Graph `$batch`	200 if the batch parses, stated	`responses[].status`
Salesforce Composite	200 either way, stated	one response per subrequest
OpenSearch `_bulk`	number not stated	top-level `errors`, per-item `status`
Elasticsearch `_bulk`	number not stated	top-level `errors`, per-item `status`
Google batch (Gmail guide)	200 in the example, no failing part shown	each multipart part’s status line

Three of them say the thing in words. AWS, for SQS: “you should check for batch errors even when the call returns an HTTP status code of 200.” Microsoft: “A 200 status code on the batch response headers doesn’t indicate that the individual requests inside the batch succeeded.” OpenSearch: “Your application should always check the errors field in the response.”

HTTP has a code made for this, 207 Multi-Status, from WebDAV (RFC 4918). The services that use it do not use it as a pass/fail signal either: RingCentral returns 207 for every batch, so it means “batch read”, and only a fully successful bulk delete gets a 204.

The rule

For any endpoint that takes a list, the status code answers one question: did you read my list? Whether each item happened is a second answer, and it lives in a per-item field. So:

Read the per-item result first, every time, including on 200 or 202.
Never read a list of successes, a queue or an accepted array, and take its emptiness as the answer. An empty success list is consistent with every item failing. (A neighbour of this rule, for a single request: a 200 can lie too, about hosts that answer 200 while serving nothing.)
If you write such an API, put the refusal where a client looks first, and say in the docs, early, that the status is not the answer. The three that say it plainly are the ones above.

What this does not show

The list is not a random draw: it is the well-known batch APIs I expected to fit, and I did not go looking for batches that fail whole on any bad item (transactional writes do exactly that, and are a different design). It shows what the documentation says, not what the services do; nothing was called. And it does not show that clients get this wrong in general. For that there is one case, the one above, which is why I went looking.