v1.0.0-ballot1
For a full list of available versions, see the Directory of published versions
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.
This specification makes rules about the use of specific HTTP status codes in particular circumstances where the status codes SHALL map to particular states correctly, and only where the correct status code is not obvious. Other HTTP status codes may be used for other states as appropriate, and this particularly includes various authentication related status codes and redirects. Authentication redirects should not be interpreted to change the location of the resource itself.
FHIR® defines an OperationOutcome resource that can be used to convey specific detailed processable error information. For a few combinations of interactions and specific return codes, an OperationOutcome is required to be returned as the content of the response. The OperationOutcome may be returned with any HTTP 4xx or 5xx response, but is not required - many of these errors may be generated by generic server frameworks underlying a FHIR® server.
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. |
| 422 Unprocessable Entity | FHIR validation errors such as invalid terminology code, wrong data type value in payload body (e.g. incorrect date format), the proposed resource violated applicable FHIR profiles (e.g. wrong data element name), or violation of LOB defined business rules. |
| 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 Interaction pages.