Batch APIs and Partial Failure

500 individual POST /contacts calls cost 500 round trips (sequential: minutes on a high-latency link), 500 authentication checks, 500 rate-limit tokens, and 500 chances for a transient failure to leave the client unsure which items landed. A POST /contacts:batch with 500 items costs one round trip and one auth check — and creates a request body large enough to need Large Requests and Documented Limits limits, a response that must describe 500 outcomes, and a failure mode the single endpoint never had: *some* of it worked.

The first contract decision is the size cap. Unbounded batches are a memory and timeout problem — a 50,000-item batch holds a connection for minutes and a transaction for as long — so the cap (100? 1,000?) is a promise about server capacity, returned as 413 or a 422 BATCH_TOO_LARGE with the limit in the error, and the client paginates its own input. The second decision is whether the batch is a convenience over the single endpoint (same validation, same authorization per item, same error codes) or a different operation with different semantics. Convenience is what consumers expect; say so, and make the per-item errors identical to what the single endpoint would have returned.

Rate-limit accounting is the decision most often left implicit. Does a 500-item batch consume one request token or 500? If one, batches become the way around rate limits and a single call can do 500 writes of work; if 500, the client must know the batch will be rejected outright when its budget has 300 left — or accepted with 300 processed and 200 marked RATE_LIMITED. Either is a defensible clause of The Rate-Limit Contract; an undocumented one is a surprise.

Best-effort batches must return a result per item, in request order, each carrying either the created resource (or its id) or an error in exactly the shape of The Error Model: Structure Over Apology — same code, same field errors, same retryability. The overall status is the awkward part: 200 with per-item failures is defensible when the batch itself succeeded ("we processed your batch; here is what happened"), and 207 Multi-Status exists for the purpose but many clients do not handle it. What is not defensible is 200 with a body that hides failures, or 400 for the whole batch because one item was invalid under a best-effort contract — see Partial Failure: When 3 of 5 Succeed for the general rule.

A summary block (succeeded: 497, failed: 3) saves the client from counting, and a failed_indices or per-item index field lets a client retry only the failures. That retry must be safe: each item should carry its own idempotency key (or a client reference id the server dedups on) so that retrying the three failures — or the whole batch after a lost response — does not create 497 duplicates. The batch-level Idempotency-Key alone is not enough once a client resubmits a *subset*; Idempotency Keys: The Mechanism explains why the key must match the operation being retried.

Ordering is the last clause. Does the server process items in request order? Does item 3 see the effects of item 2 (create a folder, then create a file in it)? For independent best-effort batches the honest answer is "no ordering guarantee, no cross-item visibility"; for batches that need sequencing, the contract should either promise in-order execution or require the client to sequence across batches.

All-or-nothing sounds safer and is often the wrong promise. It requires one transaction spanning every item — fine for 50 rows in one database, impossible when each item calls a payment provider or a downstream service (There Is No Transaction Across APIs). It also makes the batch as fragile as its worst item: one invalid email rejects 499 valid contacts, and the client has to find, fix and resubmit. It is the right promise when items are interdependent or when partial application creates an inconsistent state a human must clean up — financial postings, inventory reservations that must balance.

Best-effort is honest about independence and scales to any backend, at the cost of pushing failure handling onto the client: it must read every result, retry failures, and tolerate a world where 497 contacts exist and 3 do not. Validate-all-then-apply is the pragmatic middle for many imports — reject bad input outright, tolerate runtime failures per item — and it is worth stating that the two failure classes get different responses.

Whichever model the contract chooses, the batch endpoint should not be the *only* way to do the operation. Keep the single-item endpoint; make the batch a documented convenience with the same semantics; and when batches grow beyond what a request can hold (tens of thousands of items, minutes of work), stop pretending it is synchronous and move to a job resource (Long-Running Operations: 202 and the Job Resource).