13. Multi-Status Response

A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The default Multi-Status response body is a text/xml or application/xml HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation. 100 series status codes SHOULD NOT be recorded in a 'response' XML element.

Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations.

The 'multistatus' root element holds zero or more 'response' elements in any order, each with information about an individual resource. Each 'response' element MUST have an 'href' element to identify the resource.

A Multi-Status response uses one out of two distinct formats for representing the status:

A 'status' element as child of the 'response' element indicates the status of the message execution for the identified resource as a whole (for instance, see Section 9.6.2). Some method definitions provide information about specific status codes clients should be prepared to see in a response. However, clients MUST be able to handle other status codes, using the generic rules defined in Section 10 of [RFC2616].
For PROPFIND and PROPPATCH, the format has been extended using the 'propstat' element instead of 'status', providing information about individual properties of a resource. This format is specific to PROPFIND and PROPPATCH, and is described in detail in Sections 9.1 and 9.2.

13.1. Response Headers

HTTP defines the Location header to indicate a preferred URL for the resource that was addressed in the Request-URI (e.g., in response to successful PUT requests or in redirect responses). However, use of this header creates ambiguity when there are URLs in the body of the response, as with Multi-Status. Thus, use of the Location header with the Multi-Status response is intentionally undefined.

13.2. Handling Redirected Child Resources

Redirect responses (300-303, 305, and 307) defined in HTTP 1.1 normally take a Location header to indicate the new URI for the single resource redirected from the Request-URI. Multi-Status responses contain many resource addresses, but the original definition in [RFC2518] did not have any place for the server to provide the new URI for redirected resources. This specification does define a 'location' element for this information (see Section 14.9). Servers MUST use this new element with redirect responses in Multi-Status.

Clients encountering redirected resources in Multi-Status MUST NOT rely on the 'location' element being present with a new URI. If the element is not present, the client MAY reissue the request to the individual redirected resource, because the response to that request can be redirected with a Location header containing the new URI.

13.3. Internal Status Codes

Sections 9.2.1, 9.1.2, 9.6.1, 9.8.3, and 9.9.2 define various status codes used in Multi-Status responses. This specification does not define the meaning of other status codes that could appear in these responses.