Capability Statement > Response Handling
Response Handling
When a PPR FHIR request fails due to a request validation, or when the message has not been processed correctly by the PPR, an OperationOutcome resource will be sent in the PPR response message in addition to an HTTP status code, where applicable. 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, or in the Status Definitions of the HTTP Protocol Standard.
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 come back from a PPR FHIR query, 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 Success | The HTTP 200 OK success status response code indicates that the request has succeeded. | A 200 response is cacheable by default.The meaning of a success depends on the HTTP request method: GET/POST : The resource has been fetched and is transmitted in the message body. | |
| 400 Bad Request | This indicates that the submitted request is invalid. For example, 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, where applicable | 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 be returned in the event of a specified resource does not exist, or when the requested resource type is not supported or the endpoint is not a valid FHIR endpoint. | Yes, where applicable | 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 |
| 422 Unprocessible Entity | Indicates the request or response fails to validate the applicable FHIR profiles or business rules. For example, when PPR cannot return a practitioner with minimum demographics to the clients. | Yes, where applicable | Display the message associated with the OperationOutcome to the user and also provide information for how to contact system support for the client software. |
| 500 Internal Server Error | Indicates that the server encountered an Internal error during the process of response message | Yes, where applicable | The OperationOutcome message should be displayed to the user along with the diagnostics element and information to contact support |
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | Yes, where applicable | Client should contact support |
Operation Outcome
OperationOutcome is used to provide more 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:
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 regardless of whether the submitted content is XML or JSON.