Why Batch
Doing one HTTP call per record is slow when a client must create hundreds of items. Bulk endpoints accept an array in one request, cutting round trips and connection overhead. The challenge is what happens when some items succeed and others fail.
Partial Failure
A batch can be all or nothing, where one bad item rolls back the whole set, or best effort, where each item is processed independently. Best effort returns a per item status array so the client can retry only the failures.
Design Notes
- Cap the batch size to bound memory and latency.
- Return a structured result listing each item id and its outcome.
- Combine with idempotency keys so a retried batch does not duplicate work.
Status Codes
A best effort batch often returns 200 with a mixed body, or 207 Multi Status, rather than a single all or nothing code, because some items passed and others did not.
Key idea
Bulk endpoints process many records per call to cut round trips, and best effort batches return per item statuses so clients retry only the items that failed.