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.
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 207 Multi-Status status code is typically used by WebDAV.
The status of the resource as a whole
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.ai/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
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.ai/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.
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.
POST /signup HTTP/1.1 Host: www.example.ai Content-Type: application/xml Content-Length: 70 <?xml version="1.0"> <person> <name>David Smith</name> <country>USA</country> </person>
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.ai/signup/resource_1</d:href> <d:status>HTTP/1.1 204 No content</d:status> </d:response> <d:response> <d:href>http://www.example.ai/signup/resource_2</d:href> <d:status>HTTP/1.1 201 Created</d:status> </d:response> <d:response> <d:href>http://www.example.ai/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>
Apache HttpComponents Core
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.