Ontario IG Template
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. |
| 403 Authorization Error | The server understood your request, but it is refusing to authorize it. In other words, you do not have the necessary permissions to access the requested resource or perform the requested action, even if you are correctly authenticated. |
| 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. |
| 422 Unprocessable Entity | The FHIR resource you sent in the request body failed validation. The server could not process it because it violates certain rules, even if it was well-formed XML or JSON. |
| 429 Too Many Requests | Rate limit |
| 500 Internal Server Error | Indicates that the server encountered an Internal error during the process of response message |
| 502 Bad Gateway | A server-side error indicating that one server on the internet received an invalid or unparsable response from another server upstream. |
| 504 Gateway Timeout | Indicates a server-side problem where one server in the request chain did not receive a timely response from another server upstream that it needed to access to complete your request. |
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.
Note to IG Authors:
This is a template only. Replace these examples with actual links in the IG