2.2.8.1 Error Response

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

An in-stream error occurs when a data service that is 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. For an in-stream error, the HTTP response code, headers, and payload cannot be used to indicate that an error has occurred. This document does not prescribe an error response generation method for in-stream errors.

In the context of this document, "top-level" errors SHOULD be used when the data service that is 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 three formats for top-level error messages: XML, JSON, 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 that is formatted by using XML. Servers MUST use this format when sending a top-level error response to a request that includes an Accept (section 2.2.5.1) request header with the values "application/xml" or "application/atom+xml", or to a request that does 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".

For details about formatting an error by using the preferred OData3.0 JSON format, see [MS-ODATAJSON] section 2.1.28.

Verbose JSON Error Response (section 2.2.8.1.2) defines the rules for a top-level error in a response body that is formatted by using Verbose JSON, as specified in [RFC4627]. Servers MUST use this format when a sending top-level error response to a request that includes 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".

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     =   <Error response in JSON as per [MS-ODATAJSON]
                            section 2.1.28>
                           / <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