Previous Page Arrow Next Page Arrow

3.10 Error Payload

SData uses HTTP status codes to indicate errors. In many REST applications, a status code and a status message is sufficient. However, in business applications it is better to provide a detailed diagnoses when an error occurs. SData defines an XML format for error information.

Here is an example of an SData error entry:

<sdata:diagnosis>
  <sdata:severity>error</sdata:severity>
  <sdata:sdataCode>BadWhereSyntax</sdata:sdataCode>
  <sdata:applicationCode/>
  <sdata:message>Invalid query syntax: function 'foo' does not exist</sdata:message>
  <sdata:stackTrace/>
  <sdata:payloadPath/>
</sdata:diagnosis>

The elements of the error payload are now described:

Element Description
severity Severity of the diagnosis entry. Possible values are: * Info: Informational message - does not require any special attention. * Warning: Warning message - does not prevent operation from succeeding but may require attention. * Transient: Transient error - operation failed but may succeed later in the same condition (record locked for 'xxx'). * Error: Error: Operation failed - request should be modified before resubmitting. * Fatal: Severe error - operation should not be reattempted. Other operations are likely to fail too.
sdataCode The SData diagnosis code (see table below)
applicationCode The application specific diagnosis code. This should only be set when sdataCode is set to ApplicationDiagnosis.
message A friendly message for the diagnosis.
stackTrace The stack trace for the error. It should only be filled when the service is run in “development” mode.
payloadPath XPath expression that refers to the payload element responsible for the error. This element is only used when the error is related to a specific piece of data being sent to the service provider. For example when updating a resource, or when submitting a service request.

SData defines the following set of values for the code element:

SData diagnosis code Description
BadUrlSyntax Invalid URL syntax.
BadQueryParameter Invalid Query Parameter.
ApplicationNotFound Application does not exist.
ApplicationUnavailable Application exists but is not available.
DatasetNotFound Dataset does not exist.
DatasetUnavailable Dataset exists but is not available.
ContractNotFound Contract does not exist.
ResourceKindNotFound Resource kind does not exist.
BadWhereSyntax Invalid syntax for a where condition.
ApplicationDiagnosis Application specific diagnosis, detail is in the applicationCode element.
This list may be extended in the future. Errors that do not match a specific code should be reported with the ApplicationDiagnosis code.

One or more <sdata:diagnosis> elements can be placed inside an Atom <feed> or <entry> element. This allows an SData service to return several diagnoses for an operation. This can be useful when processing create or update requests since several business rules could give a diagnosis for a given entry, and it is useful to be able to report them all to the consumer. Some may have different severity levels.

When the response does not contain a <feed> or <entry> (for example when a GET fails), the <sdata:diagnosis> element(s) should be inserted in the <sdata:diagnoses> element. The error payload would look like this:

<sdata:diagnoses xmlns="http://schemas.sage.com/sdata/2008/1">
  <sdata:diagnosis>
    ...
  </sdata:diagnosis>
  <sdata:diagnosis>
    ...
  </sdata:diagnosis>
</sdata:diagnoses>
SData providers MUST return errors as described above.

Previous Page Arrow Next Page Arrow