207 Multi-Status

HTTP response status code 207 Multi-Status is returned by the server in cases where it is relevant to relay information about multiple resources. This is somewhat different from the other 2XX HTTP response status codes because it does not signify the success of the HTTP request. Rather, it means that an aggregate block of HTTP responses is being included in the message body.

Usage

When the 207 Multi-Status status code is received, it is in response to a HTTP request that needed to access multiple resources, or alternatively, was a compilation of more than one HTTP request. For example, if a HTTP request requires updating multiple databases, each an independent resource, then some tasks may have been successful whereas others were not.

The message body contains, by default, an XML entity with a multistatus root element. The client is responsible for parsing the nodes to determine the status of each subtask as it relates to the relevant resource.

The root contains zero or more response elements that can appear in any order. Each response element must contain an href element that specifies the resource being referred to. There are two different formats that response elements can follow; the status may refer to the whole resource, or only to specific properties of it.

The status of the resource as a whole

A child status element contains the resulting HTTP status code concerning the resource that is identified, as a whole. Some methods include information about specific HTTP status codes that are available for the client to use but in general, clients are expected to handle standard HTTP status codes.

Example status of the entire resource

<d:response>
  <d:href>http://www.example.re/tasks</d:href>
  <d:status>HTTP/1.1 200 OK</d:status>
</d:response>

The status of individual properties of a resource

In support of the PROPFIND and PROPPATCH methods, propstat can be used in place of status to inform concerning individual properties.

Example status of individual resource property

<d:response>
  <d:href>http://www.example.re/tasks</d:href>
  <d:propstat>
    <d:prop>
      <d:getcontentlanguage>"en-CA"</d:getcontentlanguage>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:prop>
  </d:propstat>
</d:response>

Indication of success or failure

The 207 Multi-Status response status code can be used to indicate overall success, overall failure, or a combination of both. The client is responsible for assessing the completeness of the overall task by examining each of the response elements.

Example

In the example, the client posts XML data to the server. The server acknowledges that the data was received and processed. Three independent resources are required for this task, and the server returns a list to show the results of the interaction with each of them.

Interactions with the first two resources are successful, with the first not returning a message body and the second indicating that a resource was created. However, the third resource reports an error because the resource is locked. It is up to the client to decide whether this is a success or failure and act accordingly.

Request

POST /signup HTTP/1.1
Host: www.example.re
Content-Type: application/xml
Content-Length: 70

<?xml version="1.0">
<person>
  <name>David Smith</name>
  <country>USA</country>
</person>

Response

HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset="utf-8"
Content-Length: 568

<?xml version="1.0" encoding="utf-8" ?>
<d:multistatus xmlns:d="DAV:">
  <d:response>
    <d:href>http://www.example.re/signup/resource_1</d:href>
    <d:status>HTTP/1.1 204 No content</d:status>
  </d:response>
  <d:response>
    <d:href>http://www.example.re/signup/resource_2</d:href>
    <d:status>HTTP/1.1 201 Created</d:status>
  </d:response>
  <d:response>
    <d:href>http://www.example.re/signup/resource_3</d:href>
    <d:status>HTTP/1.1 423 Locked</d:status>
    <d:error><d:lock-token-submitted/></d:error>
  </d:response>
</d:multistatus>

Code references

.NET

HttpStatusCode.MultiStatus

Rust

http::StatusCode::MULTI_STATUS

Rails

:multi_status

Go

http.StatusMultiStatus

Symfony

Response::HTTP_MULTI_STATUS

Python3.5+

http.HTTPStatus.MULTI_STATUS

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_MULTI_STATUS

Angular

@angular/common/http/HttpStatusCode.MultiStatus

Takeaway

HTTP response status code 207 Multi-Status is a response that contains HTTP status codes resulting from operations on multiple resources. It does not guarantee success and the client is responsible for iterating through the individual status codes to determine the specifics.

See also

• RFC 4918