HardExperience level: 8-15 years1 min read

How do you design a bulk/batch API and handle partial failures?

Reviewed by Gurusankar M.

Asked inAmazonMicrosoftDeloitte
#bulk api#batch#partial failure#207 multi-status#idempotency
Report issue

Short Answer

Accept an array of items, cap the batch size, and decide the failure model: all-or-nothing (transactional) or best-effort with per-item results. For best-effort, return a per-item status array (or 207 Multi-Status) so clients know exactly which items succeeded/failed and can retry just the failures.

On this page

Concept Made Simple

Coffee Chat Question

“How do you design a bulk/batch API and handle partial failures?”

Remember It Faster

Mind Map Answer

All-or-nothing
transactional; one fails → all roll back
Best-effort
per-item results, partial success
Response
per-item status / 207 Multi-Status
Always
cap batch size; idempotent items

Learn by Doing

Hands-on Keyboard

json
POST /orders/batch
{ "items": [ {...}, {...}, {...} ] }
-->
{ "results": [
  { "index":0, "status":201, "id":"o1" },
  { "index":1, "status":422, "error":"INVALID_SKU" },
  { "index":2, "status":201, "id":"o3" }
]}

Think Beyond the Expected

What If?

A client retries a failed batch — how do you avoid duplicating the items that already succeeded?

Make each item idempotent (client supplies a per-item key, or you dedupe on a natural key). On retry, already-processed items return their prior result instead of re-creating. Per-item idempotency is what makes batch retries safe under partial failure.

Real World

Bulk import/sync APIs (and email/SMS/order batch endpoints) return per-item results so clients retry only the failures; capping batch size protects the server from giant payloads.

Interviewer's Expectation

Keywords they're listening for:

  • all-or-nothing vs best-effort
  • per-item result / 207
  • cap batch size
  • per-item idempotency for retries
  • clear partial-failure contract

Common Mistakes

  • Single status code hiding partial failures
  • Uncapped batch sizes
  • Non-idempotent items breaking retries

Best Practices

  • Return per-item status; document the failure model
  • Cap and validate batch size
  • Make items idempotent for safe retries

Follow-up Questions

  1. When is transactional (all-or-nothing) the right model?
  2. How does 207 Multi-Status work?
  3. How do you keep batch processing within timeouts?

Continue Learning with AI

Take this question deeper with your favourite AI assistant. Pick a depth, copy the prompt, or open it directly — AI is your learning companion, not a shortcut.

Plain-language foundations

I'm preparing for a software engineering interview and want to understand this from scratch, as a beginner.

Topic: Status Codes (REST APIs)
Interview question: "How do you design a bulk/batch API and handle partial failures?"

Please:
1. Explain the core idea in simple, plain language, using an everyday analogy.
2. Define any technical terms you use.
3. Walk through one small, concrete example.
4. Finish with a single sentence I can easily remember.

Keep the tone friendly and assume I'm new to this topic.
Open inChatGPTGeminiClaude

Was this answer helpful?

Affiliate links

Tools for Your Developer Workspace

Equipment for a comfortable, productive setup.

As an Amazon Associate I earn from qualifying purchases.