What is a bulk create endpoint, and why is it a partial failure contract?
A bulk create endpoint accepts one HTTP request that carries many independent create operations, such as a POST /contacts:batch whose body is an array of fifty contact records. Each item could have been its own POST /contacts. The batch endpoint packages them into one request.
Teams build these for three reasons. Fewer round trips matter when a client sits on a high-latency link. Each request also carries fixed overhead: TLS handshakes, authentication checks, connection setup, and logging. Batching spreads that overhead across many items. Finally, client code for CSV imports and nightly syncs gets simpler when it sends one payload instead of managing a pool of concurrent calls.
The speed gain is the easy part. The hard part of rest bulk api design is deciding what happens when item 12 fails validation, item 31 hits a uniqueness conflict, and the other 48 are fine. With single-resource calls, HTTP already answers that question per request. In a batch, you have to answer it yourself, and clients will build their error handling around your answer. A batch endpoint is really a partial failure contract, and the throughput is a side benefit.
Build one if your clients routinely create many resources at once, for example through imports, sync jobs, or third-party integrations. If most clients create one or two resources at a time, the contract costs more than it saves.
This guide makes the decisions in dependency order:
- Atomicity mode: all-or-nothing or best-effort.
- Per-item result model.
- Retry semantics.
- Top-level status code (200, 201, or 207 Multi-Status). This comes last because it depends on the three choices above.
Should a batch be all-or-nothing or best-effort?
An atomic batch commits every item or none. Clients get one outcome to handle, and there is never a half-written state to clean up. Two costs come with that guarantee. First, one malformed item rejects the other 499, so clients end up pre-validating aggressively or splitting batches to isolate the bad item. Second, wrapping the whole batch in a single transaction holds locks for its full duration. Larger batches increase lock contention with other writers and push requests closer to gateway and database timeouts.
A best-effort batch processes each item independently and reports per-item outcomes. Throughput improves because valid items never wait on invalid ones, and work can run in smaller transactions or in parallel. The price is that reconciliation moves to the client. It must read every result, retry or discard the failures, and tolerate a batch that only partly succeeded.
| Concern | All-or-nothing | Best-effort |
|---|---|---|
| Client error handling | One outcome | Per-item reconciliation |
| Effect of one bad item | Whole batch rejected | Only that item fails |
| Transaction scope | One long transaction | Per item or small chunks |
| Lock and timeout risk | Grows with batch size | Bounded per item |
Neither mode is wrong, but leaving the mode undocumented is. State it explicitly in the API contract. If your clients need both, accept a request field such as mode: "atomic" | "best_effort" and apply a lower size limit to atomic requests.
Intra-batch dependencies, such as item 7 referencing a parent created by item 3, force ordered execution. They also make atomic rollback and parallel processing far harder. Reject such batches. Have clients create parents first, then send the dependents in a separate request.
How should the response body report per-item results?
Return exactly one result entry per input item, in the same order as the request. Positional correlation alone is fragile: a client that filters or reorders its array before sending loses track of which result belongs to which record. Let clients attach their own reference ID to each item and echo it back. Index plus reference ID gives two independent ways to match results.
Each entry should carry:
- status: an HTTP-style code such as 201 or 422, so clients can reuse logic they already have.
- id and location of the created resource, on success.
- error, on failure: a stable machine-readable code, a pointer to the offending field, and a human-readable message.
Keep request-level and item-level failures separate. Malformed JSON, failed authentication, the wrong content type, or a batch over the size limit means no item was evaluated. Return an ordinary 4xx for the whole request with no per-item array. Validation errors and uniqueness conflicts belong to individual items and go in their result entries.
Use the same error object shape and error codes as your single-item endpoints. A client that already handles email_taken on POST /users can then handle it inside a bulk result with the same code. You avoid a second error-parsing path to build, test, and keep in sync.
As an illustration, a request creates three users with references a, b, and c. The response lists a with status 201, its new ID and location. It lists b with status 422, code invalid_format, and pointer /email. It lists c with status 409 and code email_taken.
# Request: three users, each tagged with a client-supplied reference
POST /users/bulk HTTP/1.1
Content-Type: application/json
{"items": [
{"ref": "a", "email": "ana@example.com", "name": "Ana"},
{"ref": "b", "email": "not-an-email", "name": "Ben"},
{"ref": "c", "email": "cy@example.com", "name": "Cy"}
]}
# Response: the request itself was valid, so outcomes are reported per item.
# One entry per input, same order; index and ref both identify the item.
HTTP/1.1 200 OK
Content-Type: application/json
{"results": [
{"index": 0, "ref": "a", "status": 201,
"id": "usr_8f3k2", "location": "/users/usr_8f3k2"},
{"index": 1, "ref": "b", "status": 422,
"error": {"code": "invalid_format", "pointer": "/email",
"message": "email must be a valid address"}},
{"index": 2, "ref": "c", "status": 409,
"error": {"code": "email_taken", "pointer": "/email",
"message": "a user with this email already exists"}}
]}
# Contrast: a request-level failure has no results array at all.
HTTP/1.1 413 Content Too Large
Content-Type: application/json
{"error": {"code": "batch_too_large",
"message": "batch exceeds the maximum of 100 items"}}
A mixed-outcome bulk create where each item gets its own status, ID or error object (in the same shape a single-item POST /users would return), shown alongside a request-level 4xx that carries no per-item results.
Which HTTP status code should a bulk endpoint return: 200, 201 or 207 Multi-Status?
With per-item results in the body, the top-level status code says less than it does on a single-resource endpoint. It still matters, because proxies, client libraries and dashboards act on it.
When every item succeeds, return 201 Created if the batch created resources, or 200 OK if your API treats the batch as one operation. Don't send a single Location header, because there is no single resource. The per-item locations belong in the body. When the request itself is invalid, such as malformed JSON, too many items or failed authentication, return the usual 4xx and no item results.
Mixed outcomes are where you have to choose:
| Option | What it communicates | Tooling behaviour | Main risk |
|---|---|---|---|
| 207 Multi-Status | "Look inside; outcomes differ" | Some HTTP clients, SDK generators, proxies and dashboards treat it as unknown or plain success | Generated clients may not model the 207 response body |
| 200 with per-item results | "Request processed" | Handled everywhere | Status-code-based alerting never sees item failures |
207 comes from WebDAV, where it was defined for responses that carry several independent statuses. That makes it the most precise signal, but it is uncommon outside WebDAV, so check your gateway, client generator and metrics pipeline before adopting it. If you choose 200, emit a separate metric or log field for failed items. Otherwise a batch where half the items failed looks healthy on every graph.
Whichever code you pick, clients must inspect the item results and not stop at the top-level code. A client that checks only for a 2xx will mark the b and c items above as saved and silently lose them. Put this requirement in your documentation and in your reference client.
How do you make batch requests safely retryable?
A client that times out on a bulk create cannot tell whether the server applied none, some, or all of the items. Without idempotency, resubmitting is a guess that can create duplicates.
Keys at two levels
Accept an Idempotency-Key header for the whole request, and a client-generated key on each item. The request key lets the server recognize an exact replay. The item keys matter more for partial failure, because a retry usually carries a subset of the original items. Without item keys, the server cannot match those items to earlier attempts.
What a replay returns
On a replay, return the stored per-item results, not a fresh evaluation. Items that were created before return their original success entries with the same resource IDs. Items that failed with a non-retryable error return the same error. Only items with no stored outcome are processed now. If a request key arrives with a different payload, reject it with a 4xx error rather than guessing which version the client meant.
The cost
You must store keys and responses for a retention window and document how long it is. After expiry, a replay becomes a new request. The key write and the item insert need to commit together, or a crash between them breaks the guarantee. Concurrent replays of the same key also need a lock or a unique constraint.
Client loop sketch
- Send the batch, with a stable key on every item.
- On timeout, resend the same batch with the same keys.
- On a response, collect only the items marked retryable.
- Wait with exponential backoff and jitter, then resend those items with their original keys.
- Stop after a maximum number of attempts and surface whatever items remain unresolved.
import { randomUUID } from "node:crypto";
type Item = { key: string; [field: string]: unknown }; // key is set once by the caller
type Result = { key: string; status: "created" | "failed"; retryable?: boolean };
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
export async function bulkCreate(url: string, items: Item[], maxAttempts = 5) {
let pending = items;
let requestKey = randomUUID(); // reused only while the payload is byte-for-byte the same
const final = new Map<string, Result>();
for (let attempt = 0; attempt < maxAttempts && pending.length > 0; attempt++) {
// Full-jitter exponential backoff before every retry: random delay in [0, 200ms * 2^attempt).
if (attempt > 0) await sleep(Math.random() * 200 * 2 ** attempt);
let res: Response;
try {
res = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json", "Idempotency-Key": requestKey },
body: JSON.stringify({ items: pending }),
signal: AbortSignal.timeout(10_000),
});
} catch {
continue; // timeout or network error: outcome unknown, resend the same batch with the same keys
}
if (res.status === 429 || res.status >= 500) continue; // whole request retryable, payload unchanged
if (!res.ok) throw new Error(`bulk create rejected: ${res.status}`);
const results: Result[] = (await res.json()).results;
for (const r of results) if (!r.retryable) final.set(r.key, r); // created or permanently failed
const retryKeys = new Set(results.filter((r) => r.retryable).map((r) => r.key));
pending = pending.filter((i) => retryKeys.has(i.key)); // same items, same item keys
requestKey = randomUUID(); // subset is a new payload, so it needs a new request key
}
// Anything still pending is unresolved; surface it instead of dropping it.
return { results: [...final.values()], unresolved: pending };
}
A client retry loop that resends an identical batch with the same request key after a timeout or 5xx, then resends only the items marked retryable with their original item keys and a fresh request key, using jittered exponential backoff and returning unresolved items after the attempt limit.
When should you use limits, async jobs, or avoid bulk endpoints entirely?
Every bulk endpoint needs two published limits: a maximum item count and a maximum payload size. Check both before processing any item. If a request exceeds either one, reject the whole request with a single request-level error, not per-item failures. Use 413 when the body is too large. Use 400 or 422 when there are too many items, and include the limit in the error body so clients can split the batch correctly.
Set the limits from your timeouts and your transaction size. If the batch is all-or-nothing, the item count also bounds how long locks are held. If it is best-effort, the count bounds how much work must finish before the gateway or client timeout. Large limits raise memory use and timeout risk, and one bad request can affect more data. Small limits move the cost to clients, who then need more round trips, more retry loops and more connection overhead.
Switching to an async job
When a batch can't reliably finish within the request timeout, return 202 Accepted with a job resource in the Location header. The client polls that resource for status and, once the job finishes, for the same per-item results the synchronous endpoint would return. Document how long job results are kept and what a poll returns after they expire. This flow has its own costs: polling traffic, storage for job state and results, and client code that must handle jobs that are pending, failed or expired.
When to avoid a bulk endpoint
- Low volumes. If clients rarely send more than a few items, single-item calls are simpler to build and debug.
- Strong cross-item dependencies. If items reference each other, design a dedicated domain operation instead.
- Clients that can't handle partial results. Best-effort semantics push reconciliation work onto the caller, and some callers can't do it.
+--------+ POST /batch +------------------------------------------+
| Client |---------------->| Limit check before processing any item: |
+--------+ | max item count, max payload size |
+------------------------------------------+
| | |
body too large too many items within limits
v v v
+--------------+ +----------------+ +----------------+
| 413: reject | | 400/422: reject| | Can finish in |
| whole request| | whole request, | | request |
| | | limit in body | | timeout? |
+--------------+ +----------------+ +----------------+
| |
yes | | no
+---------------------+ |
v v
+---------------------------+ +-------------------------+
| Sync: per-item results | | 202 Accepted |
| (all-or-nothing: count | | Location: /jobs/{id} |
| bounds lock duration) | +-------------------------+
+---------------------------+ |
v
+--------+ +--------------------------------------------+
| Client |--GET /jobs/{id}--->| Job status: pending, done, failed |
+--------+<----- results -----| done: same per-item results as sync |
| results kept for a documented period |
| after expiry: documented poll response |
+--------------------------------------------+
Limits are checked before any item is processed. Oversized requests are rejected as a whole. Batches that fit the request timeout return per-item results synchronously, and larger ones return 202 with a job resource that the client polls until the results expire.
What are the alternatives to a bulk endpoint, and how do they affect development cost?
Three alternatives cover most of the same use cases. Each moves cost to a different place.
| Approach | What you build | Where the cost lands |
|---|---|---|
| Parallel single-item requests over reused connections | Nothing new; the existing endpoint is reused | Clients: concurrency limits, backoff, aggregating errors themselves |
| File upload plus async job | Job store, status endpoint, result file, retention cleanup | Platform: workers, job state, tracing across queue hops |
| Generic batch envelope wrapping sub-requests | A dispatcher that routes nested requests | Everyone: per-sub-request auth, nested status codes, harder docs and SDKs |
A dedicated bulk endpoint saves engineering time when its result model is shared across resources. SDKs write one partial-failure handler instead of one per resource. Idempotency keys let clients retry automatically rather than paging someone to check what was created. Per-item results with stable indexes also prevent reconciliation incidents, where a timeout leaves nobody sure which rows exist.
The cost is real, though:
- You have to store idempotency records and expire them.
- Every resource that gets a bulk variant needs its own validation rules and documentation.
- Observability gets harder because one request now produces many outcomes. Logs and metrics need per-item counts, not just a status code.
Design checklist
- Mode: All-or-nothing or best-effort, stated explicitly per endpoint.
- Result model: Per-item status, index or client reference, and error code.
- Status code: Chosen once and applied consistently, with semantics documented.
- Retries: Idempotency key scope and retention window defined.
- Limits: Maximum item count and payload size enforced, with a clear rejection error.
- Async processing: A threshold above which requests are routed to a job.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to rest bulk api design, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.