Ontario Provincial Consent Override Interface HL7® FHIR® Implementation Guide v1.0.0-draft1
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.
A PCOI response will always respond with a FHIR OperationOutcome resource after processing of a Consent Override Request, regardless of success, failure, or mixed results, in addition to an HTTP status code. Please note that other HTTP error codes may also be returned by ONE Access Gateway which can be found in the ONE Access Gateway Transport Specification here.
Table: Gateway HTTP Response Codes
| HTTP Status | Scenario Decription | OperationOutcome? | Client Expected Behavior |
|---|---|---|---|
| 201 Created | Indicates the submitted resource was accepted. | No | Display a message to the user indicating the resource was successfully submitted. |
| 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 |
| 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. | 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 |
| 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 | |
| 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 |
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 Behaviour" section for the Create Consent interaction