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:
|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.