207 - Multi-Status

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

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

Decision Support

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