207 - Multi-Status

Start Here

Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.

This page is part of the Error Reference library. Learn more about the project or report a correction.

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

1. 1Loop & Parse: Do not treat 207 as a blanket success. Iterate through the results array in the body and evaluate each status field individually.
2. 2Selective Retry: Extract only the IDs of failed items and resubmit them. Never retry the entire batch to avoid duplicating already-created resources.
3. 3Check for Error Details: Inspect the message or error objects inside each sub-response to understand why specific items failed.
4. 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

1. 1Examine the response body: Is it a flat array of results or a nested map? Modern APIs prefer: {"results": [{ "status": 201, ... }, { "status": 400, ... }]}.
2. 2Verify the Content-Type: Ensure it is application/json (REST) or application/xml; charset="utf-8" (WebDAV).
3. 3Use a JSONPath query like $.results[?(@.status >= 400)] to instantly isolate failed operations in a large batch.
4. 4Check for a summary object in the response root, which often provides counts for success, failure, and total.

{
  "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
  }
}

Seen in Production

Debugging Tools

• -JSONPath Provider: $.results[?(@.status >= 400)] - Use this to audit logs for partial batch failures.
• -Postman Visualizer: Create a script to turn 207 results into a color-coded Success/Failure table.
• -Charles Proxy: To verify the order of sub-responses matches the order of original request items.

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 summary field 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 Accepted instead of 207 to avoid keeping the connection open for minutes.

Related Errors

Official References

• -MDN Web Docs: 207 Multi-Status
• -Google Cloud API Design: Batch Operations
• -RFC 4918 Section 13 (WebDAV) & Modern REST Patterns
• -HTTP Official Documentation