Ontario Provenance HL7® FHIR® Implementation Guide -v1.0.0-trial-use
For a full list of available versions, see the Directory of published versions
FHIR Artifacts > 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.
The following table lists the HTTP codes that may come back from an HTTP call, the type of circumstances when such a response might occur, whether an OperationOutcome may or must be present (and what it will contain) and the general sort of behavior that the client system should execute.
| Code | Circumstances | OperationOutcome? | Client Expected Behavior |
|---|---|---|---|
| 200 OK | Indicates the submitted request was successful. In certain circumstances (e.g. when a consent block is in place) the request will not return the requested resource but will instead return an OperationOutcome indicating the reason the request wasn't completed. | No | |
| 201 Created | Indicates the submitted resource was accepted. | No | |
| 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. | Yes | Display the message associated with the OperationOutcome to the user and also provide information for how to contact system support for the client software. The OperationOutcome.issue.diagnostics and location should be made available as well. |
| 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. | No | The client system should re-authenticate and re-transmit the request once a new token is received |
| 403 Forbidden | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort | No | Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process |
| 404 Not found | This will only be returned in the event of a specified resource does not exist. | No | Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process |
| 409 Conflict | This indicates an integrity issue with the resource being created, such as attempting to create a duplicate resource that already exists. | No | Modify the request to resolve the conflict (e.g., generate a new unique identifier if the previous one was a temporary collision or retry with different parameters) |
| 415 Unsupported Media Type | The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format. | No | Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process |
| 500 Internal Server Error | Indicates that the server encountered an Internal error during the process of response message | Yes | The service encountered an internal error and could not complete the request. Please retry later or contact support if the issue persists. |
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | Yes | The OperationOutcome message should be displayed to the user indicating when they should expect to be able to successfully retry the request and be able to cancel out. There's no need to expose system support information |
| 504 Gateway Timeout | Indicates that one server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser. | No | The request timed out while processing. Retry the request or contact support if the issue persists. |
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.
When an OperationOutcome is returned to indicate that the resource is blocked by a patient consent directive, the following elements will be populated: