2.2.8.1 Error Response

Note: Some of the information in this section is subject to change because it applies to a preliminary implementation of the protocol or structure. For information about specific differences between versions, see the behavior notes that are provided in the Product Behavior appendix.

This section defines the structure of a response payload if a request to a data service completed in error. This section defines two types of error conditions: "in-stream" and "top-level" errors.

In-stream errors occur when a data service processing a request detects an error after the status line and zero or more response headers and potentially part of the response body have been sent to the client. In this case, the HTTP response code, headers, and payload cannot be used to indicate an error has occurred. This document does not prescribe an error response generation method for errors of this type.

In the context of this document, "top-level" errors SHOULD be used when the data service processing a request detects that an error has occurred before the status line or any response headers have been sent to the client. This document defines two formats for top-level error messages (XML and Verbose JSON, as specified in [RFC4627]).

XML Error Response (section 2.2.8.1.1 ) defines the rules for a top-level error in a response body formatted using XML. Servers MUST use this format when sending top-level error responses to requests that include an Accept (section 2.2.5.1) request header with the values "application/xml" or "application/atom+xml", or to requests that do not include an Accept (section 2.2.5.1) request header. When formatting error responses by using XML, servers SHOULD include a Content-Type response header with the value "application/xml".

Verbose JSON Error Response (section 2.2.8.1.2 ) defines the rules for a top-level error in a response body formatted by using Verbose JSON, as specified in [RFC4627]. Servers MUST use this format when sending top-level error responses to requests that include an Accept (section 2.2.5.1) request header with the value "application/json; odata=verbose". When formatting error responses by using Verbose JSON, servers SHOULD include a Content-Type response header with the value "application/json; odata=verbose".

Servers sending responses indicating top-level errors MUST use one of these two formats in the response payload.

The syntax of a top-level error response is defined as follows:

stdError-Resp         =   Status-Line              ; see [RFC2616] section 6.1.1
                          stdError-RespHeaders
                          CRLF
                          stdError-RespBody

stdError-RespHeaders  =   DataServiceVersion       ; see section 2.2.5.3
                          [Content-Type]           ; see section 2.2.5.2
                          *(HTTP-Header-Types)

stdError-RespBody     =   <XML representation of a top-level error as defined in
                           section 2.2.8.1.1>
                          / stdErrorVJson-RespBody  ; see section 2.2.8.1.2

Listing: Top-level Error Response ABNF Grammar