Capability Statement Index > Response Handling
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.
HTTP Status Codes
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. | Optional. OperationOutcome will only be returned if there is additional information or warning that need to be provided. | |
| 201 Created | Indicates the submitted resource was created. | Optional. OperationOutcome will only be returned if there is additional information or warning that need to be provided. | |
| 202 Accepted | Indicates the submitted resource was accepted. | Optional. OperationOutcome will only be returned if there is additional information or warning that need to be provided. | |
| 400 Bad Request | When there was syntactical error such as a missing or invalid header, a missing or invalid URL parameter, a request body that can't be parsed or doesn't conform to the basic FHIR JSON/XML syntax rules, etc. | Yes if the error occurs at the LOB level No if the error occurs at the gateway level |
|
| 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 | There are coarse grained authorization and fine grained authorization at the LOB level in addition to the header authentication at the gateway. The coarse grained auth requirement is applicable to all LOB. The fine grained auth requirement is optional - depending on whether there are different permissions for different resources - applicable to both data in and data out. | No - if the error occurs before the LOB | |
| 404 Not found | This will only be returned in the event of a specified resource does not exist. | Yes if the error occurs at the LOB level No if the error occurs at the gateway level |
|
| 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 | |
| 406 Not Acceptable | Accept header requests a format that the server does not support | Yes - this is a FHIR server level error | |
| 412 Precondition Failed | Yes | ||
| 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 a backend error happened | Yes - if the error occurs at the LOB level No - if the error occurs at the gateway level |
|
| 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 | Downstream system(s) did not return timely response. | Optional. Yes if an LOB error occurred |
Operation Outcome
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.