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.