API Responses
The HDSI, AMI and BIS all behave in a similar manner at the HTTP layer. Responses from the server use the HTTP error response code to indicate the classification of error, and an error result in JSON is returned to the caller so that specific details of the error can be parsed and conveyed to end-users.

HTTP Response Codes

Code
Error
Description
200
OK / No Error
This error condition indicates that the entire operation succeeded and the response represents the desired operation.
201
Created
This status code indicates that the resource was created on the server and additional processing may occur.
204
No Content
The action succeeded, however there is no content to the response.
302
Moved
This status code indicates a redirect. This is used when a request is made to an HDSI interface on a server where a remote IDataPersistence is configured (such as in a load balancing or migration scenario).
400
Bad Request
This response code indicates that there was no possible way for the HDSI to comprehend the request sent to it. This is typically done when a low level processing instruction fails (such as bad compression data)
401
Unauthorized
This response code indicates that the requested resource requires permissions which are above the current permission set of the user. This may indicate that the current user is ANONYMOUS and is trying to access a protected resource, OR may indicate a desire by the HDSI interface for the client to elevate themselves.
403
Forbidden
This response code indicates that the authorized user is not permitted to access the requested resource. This represents a full DENY policy decision.
404
Not Found
This response code indicates that the resource requested cannot be found.
405
Method not allowed
This response code indicates that the client attempted to perform an operation on the HDSI interface which is not permitted.
409
Conflict
This response code indicates that an update failed because of a formal validation constraint. Or a patch application failed due to test failure.
410
Gone
This response code indicates that the resource being requested DID exist, however has since been obsoleted.
415
Unsupported Media Type
This response code indicates that it is not possible for the HDSI to process the request content. This error typically occurs when the client is submitting data which is not JSON nor XML.
422
Entity could not be processed
The server understood the request (content/type and content) however was unable to process the request due to some state issue or business rule violation.
500
Server Error
This error indicates that the server encountered an error while trying to perform the operation.
503
Service Unavailable
This error indicates that the HDSI service is temporarily unavailable due to current startup or partial startup (i.e. an error occurred starting the HDS).

Error Response Payload

Whenever an error condition is encountered, the API will return a structured JSON or XML error response / payload. This payload indicates the reason for the failure. The payload in XML is illustrated below:
1
HTTP/1.1 500 Internal Server Error
2
Date: Thu, 27 Aug 2020 20:39:09 GMT
3
Content-Type: application/xml
4
Content-Length: 1716
5
Connection: keep-alive
6
X-PoweredBy: SanteDB 2.0.26.36666 (Kelowna)
7
X-GeneratedOn: 2020-08-27T16:39:09.4334858-04:00
8
9
<?xml version="1.0"?>
10
<RestServiceFault xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://santedb.org/fault">
11
<type>TypeOfException</type>
12
<message>Human Readable Message</message>
13
<stack>
14
In Debug Mode
15
The Stack Trace
16
Where The Error Was Thrown
17
</stack>
18
<policyOutcome>Outcome of Policy Decision</policyOutcome>
19
<policy>ID of Policy</policy>
20
<rule id="id-of-business-rule-violated" priority="W" type="UUID">Description of business rule violation</rule>
21
<cause>
22
... Another Service Fault ...
23
</cause>
24
</RestServiceFault>
Copied!