207 - Multi-Status
HTTP 207 Multi-Status is a success response indicating that the server has processed a batch request and the body contains multiple independent status codes for each sub-operation. It allows for "Partial Success," where some items in a batch succeed while others fail.
Last reviewed: March 12, 2026|Editorial standard: source-backed technical guidance
What Does Multi-Status Mean?
A 207 status signals that the "transport layer" succeeded, but the "application layer" has mixed results. It is the primary solution for non-atomic batch operations. The critical risk is the "False Success Trap": checking only the top-level 207 status and ignoring the individual 4xx/5xx errors hidden inside the payload. This code is the standard for WebDAV and modern Bulk REST APIs.
Common Causes
- -Batch Processing: A single POST request triggers multiple operations (e.g., "Create 100 Users"); some succeed (201) and some fail due to validation (400) or conflicts (409).
- -Partial Dependency Failure: In a batch update, Item A and B succeed, but Item C fails because a related resource was missing.
- -WebDAV Operations: Moving or copying a folder where some files are locked or have insufficient permissions.
- -Sync Engines: Synchronization tasks where most records are in sync, but a few have version conflicts (ETag mismatches).
How to Fix Multi-Status
- 1Loop & Parse: Do not treat 207 as a blanket success. Iterate through the
resultsarray in the body and evaluate eachstatusfield individually. - 2Selective Retry: Extract only the IDs of failed items and resubmit them. Never retry the entire batch to avoid duplicating already-created resources.
- 3Check for Error Details: Inspect the
messageorerrorobjects inside each sub-response to understand why specific items failed. - 4Handle Atomicity: If your operation requires all-or-nothing success, reconsider using a 207; use 400/422 if the entire batch must fail on a single error.
Step-by-Step Diagnosis for Multi-Status
- 1Examine the response body: Is it a flat array of results or a nested map? Modern APIs prefer:
{"results": [{ "status": 201, ... }, { "status": 400, ... }]}. - 2Verify the
Content-Type: Ensure it isapplication/json(REST) orapplication/xml; charset="utf-8"(WebDAV). - 3Use a JSONPath query like
$.results[?(@.status >= 400)]to instantly isolate failed operations in a large batch. - 4Check for a
summaryobject in the response root, which often provides counts forsuccess,failure, andtotal.
207 Decision Matrix: Success vs. Failure
- -Top-level 207: The batch was received and processed.
- -Sub-response 2xx: Individual item succeeded.
- -Sub-response 4xx/5xx: Individual item failed. Needs manual intervention or specific retry.
The Idempotency Risk
- -Retrying a full 207 batch is dangerous. Without "Idempotency Keys," items that returned 201 (Created) will be duplicated on retry. Always filter for failed IDs only.
Implementation Examples
{
"summary": { "total": 2, "success": 1, "failed": 1 },
"results": [
{
"id": "item_001",
"status": 201,
"message": "Resource created successfully"
},
{
"id": "item_002",
"status": 409,
"error": "Conflict: Resource with this ID already exists"
}
]
}const response = await fetch('/api/bulk-update', { method: 'POST', body: data });
if (response.status === 207) {
const { results, summary } = await response.json();
if (summary.failed > 0) {
const failedItems = results.filter(r => r.status >= 400);
console.error('Partial Failure Detected:', failedItems);
// Trigger targeted retry or alert user
}
}How to Verify the Fix
- -Verify that the UI correctly displays which items failed, rather than showing a global "Success" message.
- -Confirm that the retry logic only targets the items that returned a non-2xx sub-status.
- -Ensure that after fixing individual errors, the subsequent batch returns all 2xx statuses.
How to Prevent Recurrence
- -Rich Response Schema: Design your 207 bodies to include a
summaryfield at the top for instant client-side detection of partial failures. - -Standardize SDKs: Force your internal HTTP clients to throw a "PartialSuccessException" when 207 is encountered, ensuring sub-results are not ignored.
- -Validation First: Perform a "Dry Run" or validate all items synchronously before starting the actual batch execution if possible.
- -Pro-tip: For very long-running batches, use
202 Acceptedinstead of207to avoid keeping the connection open for minutes.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.