Conformance Requirements > Response Handling
When a PCR FHIR request fails due to a request validation, or when the message has not been processed correctly by the PCR, an OperationOutcome resource will be sent in the PCR response message in addition to an HTTP status code, where applicable. Please note that other HTTP error codes may also be returned by the ONE Access Gateway which can be found in the ONE Access Gateway Transport Specification.
OperationOutcome resources are sets of error, warning and information messages that provide detailed information about the outcome of an attempted system operation. They are provided as a direct system response, or component of one, and provide information about the outcome of the operation.
The following table lists the HTTP response status codes that may be returned from a PCR FHIR query, circumstances when such a response might occur, whether an OperationOutcome will be present (and what it will contain), and the steps a client system should execute to remediate identified errors.
| HTTP Code | Circumstances | OperationOutcome? | Client Expected Behavior |
|---|---|---|---|
| 400 Bad Request | Request is invalid. For example, a system URL is malformed or the query parameters do not meet the minimum search criteria required. Typically, this indicates an error with the software design of the client system, but in cases where the client does not validate inputs before submission (e.g. minimum criteria), it is possible that allowing the user to correct search parameters could result in a successful response. | Yes, where applicable | Optionally display the message associated with the OperationOutcome and inform the user to contact system support for the client software. |
| 401 Unauthorized | Request has been made without a valid ‘Authorization’ token included as an HTTP header. 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 | Re-submit the request with a valid ‘Authorization’ token included as an HTTP header. |
| 403 Forbidden | Request was valid, but the server is refusing action. The client system has not been assigned the necessary account and/or permissions for the target resource. | No | Inform the user to contact system support for the client software. Engage OHDS to verify the account and/or permissions granted to the client system, and re-submit the request. |
| 404 Not Found | Request is for a specified resource that does not exist, or the endpoint is not a valid FHIR endpoint. | No | Re-submit the request with a supported resource or PCR FHIR endpoint defined. |
| 405 Method Not Allowed | Request includes an HTTP verb that is not supported by the interface. Currently only GET and POST verbs are supported. Other verbs such as PUT and DELETE will be rejected with this error. | No | Re-submit the request with a supported HTTP verb defined. |
| 422 Unprocessible Entity | Request or response message validation failed per defined FHIR profiles or business rules. For example, when an unsupported resource, type or use code, or profile URL is defined on the request message, or the edge case where the PCR cannot return the minimum demographics required to constitute a patient on the response message (e.g. missing name). | Yes, where applicable | Optionally display the message associated with the OperationOutcome and inform the user to contact system support for the client software. |
| 500 Internal Server Error | Optionally display the message associated with the OperationOutcome and inform the user to contact system support for the client software. | Yes, where applicable | Optionally display the message associated with the OperationOutcome and inform the user to contact system support for the client software. |
| 503 Service Unavailable | Indicates that the service has been temporarily taken down. | Yes, where applicable | Optionally display the message associated with the OperationOutcome and inform the user to contact system support for the client software. |
An OperationOutcome is used to provide a detailed description of any issues that occurred during execution of a registry operation. Specific profiles are provided on the resource to reflect expectations of its use for each registry. However, the general conventions are the same:
An 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 (HTTP 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.
An OperationOutcome 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 implement logic based on the specific code returned.
The details of the issue or warning will be found in OperationOutcome.issue.details.text. This content may be displayed to the user
The OperationOutcome.issue.details.coding, 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
The OperationOutcome.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 regardless of whether the submitted content is XML or JSON.
Powered by SIMPLIFIER.NET