What is Batch Request?
Also called Bulk API, Batching.
A batch request bundles several operations into one API call so they are transmitted and processed together. Bulk endpoints accept an array of records for a single operation, while generic batching accepts a list of independent sub-requests. Batching reduces per call overhead and round trips, at the cost of more complicated partial failure handling.
The savings come from amortizing fixed costs. Every individual call pays for connection setup, authentication, routing, and rate limit accounting, which can exceed the cost of the work itself for small operations. Submitting a thousand records as ten batches of a hundred converts a thousand of those overheads into ten, and often counts as far fewer requests against a quota.
Partial failure is the central design question. A batch may be all or nothing, so any error rolls the whole thing back, or best effort, returning a per item status array. Best effort is more common because a single malformed record should rarely block nine hundred valid ones, but it forces the client to inspect every item result rather than trusting the overall status code.
Batches must be bounded and retryable. Providers cap item counts and payload size, and clients should chunk accordingly, apply backoff when throttled, and attach an idempotency key so a retry after a timeout does not create duplicates. Ambiguous outcomes are more damaging in batches because a single uncertain response covers many records.
Very large jobs are usually handled asynchronously instead. The client uploads a file or submits a job, receives an identifier immediately, and polls or waits for a callback while the provider processes the set in the background, returning a result file describing what succeeded and what failed.
Key points
- Many operations sent and processed in one call
- Amortizes connection, auth, and quota overhead
- Best effort batches need per item result checks
- Respect size caps; chunk, back off, and use idempotency keys
- Very large sets move to asynchronous job APIs
In practice
A synchronization job has twelve thousand contacts to upsert. Rather than twelve thousand calls, it sends batches of two hundred with an idempotency key per batch. One response reports one hundred and ninety-seven successes and three failures with reasons, so the job records those three for review and continues. A timed-out batch is retried with the same key and is absorbed as a duplicate rather than applied twice.