Capability Statement Index > Response Handling
Response Handling
In FHIR, errors can be detected and processed at two different layers - the HTTP layer and the FHIR layer. HTTP errors are returned in the HTTP response code that is part of the HTTP specification. FHIR errors and warnings are returned using the OperationOutcome resource. In some cases, both may be present. This page provides some general guidance around the types of error handling behavior client systems should expect from the Patient Summary Solution.
Operation Outcome
OperationOutcome is used to provide more detailed description of any issues that occurred during execution of an operation. The general conventions for OperationOutcome are:
OperationOutcome can either be the sole response to an operation (generally accompanying an HTTP code that indicates a failure) or it can be part of a Bundle indicating potential warnings associated with the generation of the search response.
If an OperationOutcome is returned with anything other than a success (200), the issues it contains will be of type 'error' or 'fatal'. Fatal is used for issues that occur before the query can be exercised, 'error' is used for issues that occur during query execution.
OperationOutcomes returned as part of a Bundle will only contain 'warning' and 'information' messages. The user should always be made aware of the existence of these messages and the user should have the opportunity to review all such messages
The OperationOutcome.issue.code provides a standardized description of the issue. Systems MAY create logic based on the specific code returned
The details of the issue or warning will be found in issue.details.text. This content should always be displayed to the user
The issue.details.coding values, issue.diagnostics and issue.location are intended for diagnostic purposes and will generally only be relevant to help-desk personnel. It may be appropriate to make access to this information available only by clicking on a button rather than displaying information to the user that may be confusing
issue.location will only occur if the problem is with a submitted FHIR instance (i.e. it will not be present if the issue is for query parameters, HTTP headers, etc.) It will be expressed as an XPath.
Gateway HTTP Response Codes
Table: Gateway HTTP Response Codes
| HTTP Status | Scenario Decription |
|---|---|
| 400 Bad Request | This indicates that the submitted request is invalid. For example, the URL is malformed, the query parameters are badly formatted or do not match the required data type. Typically, this indicates an error with the software design of the client system, but in cases where the client does not validate inputs (e.g. dates) before submission, it is possible that allowing the user to correct search parameters could result in a successful response. |
| 401 Unauthorized | Indicates the request has been made without the appropriate authorization token. This should only occur if the authorization token in use has expired - as no system should make a query without having an authorization token in place. |
| 404 Not found | This will only be returned in the event of a specified resource does not exist. |
| 405 Method Not Allowed | A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource. |
| 429 Too Many Requests | Rate limit |
| 500 Internal Server Error | Indicates that the server encountered an Internal error during the process of response message |
In all the cases above except for the successful authorization, Gateway will respond with appropriate FHIR response to the client using an OperationOutcome Resource (Ref. http://hl7.org/fhir/R4/operationoutcome.html).
For additional Response Codes see the "Expected Behavior” section of the respective Operation pages.