Bulk endpoints and partial failure reporting

What it is

A bulk endpoint takes many items in one request: create 500 contacts, update 50 prices, or, as in Microsoft Graph JSON batching (cited), wrap up to 20 arbitrary sub-requests in one HTTP call. Two behaviours exist. Atomic: all items are applied or none. Partial success: the server applies what it can and reports each failure. Google's AIP-233 (cited) requires a synchronous batch create to be atomic, and its rationale explains why: an OK status implies everything worked, so adding partial-failure information to a synchronous response later would silently change what existing clients assume. Asynchronous batches, which return an operation, may support partial success and report failures as a map from request index to a status object; transient errors the server will retry must not appear there, and when every item fails the operation itself is marked failed.

Why it matters

Clients retry bulk requests. With atomic semantics a retry is safe; with partial success a retry re-submits already-applied items unless the client can tell which ones failed. The reporting format decides whether retries create duplicates.

How to apply

• Choose one behaviour per endpoint, document it and never change it in place; moving from atomic to partial success needs a new version or an explicit flag that defaults to the old behaviour (AIP-233 describes return_partial_success).
• Report the request-level status separately from per-item results. Graph returns 200 for any parseable batch, gives each sub-response its own status, and states that 200 on the batch does not indicate that the individual requests succeeded.
• Address failures by index, or by a client-supplied id that must be unique within the batch, and reuse the single-item error shape so client code paths are shared.
• Cap the batch size and state the cap. Enforce authorisation, validation and rate limits per item; Graph evaluates each request individually against throttling and fails that request with 429.
• Support ordering only when needed; Graph's dependsOn fails dependants with 424 (Failed Dependency) when a prerequisite fails.
• WebDAV's 207 (Multi-Status) (RFC 4918, cited) exists for multiple per-resource statuses, but general clients and proxies do not know it; a JSON body with per-item status is more portable.

Pitfalls

A partial-success endpoint that returns a bare 200 and buries failures in a log. Echoing request payloads back in error entries, which AIP-233 rejected for data-sensitivity reasons. Batches whose processing exceeds the gateway timeout: past a certain size, bulk work belongs in a long-running operation.