When an error occurs during a request to a FHIR API, an OperationOutcome resource is returned along with an appropriate HTTP status code (500, 404, etc.). This is expected behavior and is generally handled by applications without difficulty.
An OperationOutcome can also be returned inside a searchset Bundle, alongside other resource types and accompanied by a 200 (success) status code. Consuming applications do not always check for this.
Three severity codes are significant here: information, warning and error. Ignoring OperationOutcomes with any of these codes can lead to incomplete or incorrect data being presented to users. Here are examples of how each severity code might be used, and what ignoring it can mean.
information
A hybrid FHIR server is kept in sync with a legacy EHR. Updates occur every night, and an OperationOutcome is included in each searchset Bundle documenting the time of the last update. The sync process fails over a weekend, and because clinician-facing applications fail to read the diagnostic message in the OperationOutcome, they do not notify users that the data being displayed may be out of date.
warning
Access to sensitive patient records in a FHIR server is restricted based on specific security labels. Where patient records are excluded for this reason, an appropriate OperationOutcome may be included in the Bundle returned. An application runs a search query to get all patients who need a follow-up appointment. One patient falls under the restricted access criteria that require elevated privileges to read, but because the code reading the patient Bundle fails to check for an OperationOutcome, this patient does not receive a follow-up appointment. Nobody knows this has occurred and the problem is not identified until the patient chases it up.
error
A commercial FHIR server truncates the number of resources returned in response to the _revinclude parameter. When it does this it includes an OperationOutcome with a severity of error to notify consuming applications. A new internal process at a clinic increases the number of Observations made during a typical encounter, causing their systems to trigger the truncation error for the first time. This goes unnoticed as code does not check for an OperationOutcome, and manifests as random Observations not appearing on screens.
OperationOutcomes with a fatal severity are seldom missed, as they are usually returned as the sole resource, and not part of a larger Bundle.
Not handling OperationOutcomes in searchset Bundles is common. When problems appear, they often do so in unpredictable ways, manifesting as missing resources, or extra resources in the case of search parameters that were not actioned.
Code that wraps FHIR queries needs to check for OperationOutcomes inside Bundles at all times, and needs to know what to do in specific cases when one is encountered.
---
Download my “FHIR Architecture Decisions” book
FHIR Weekly
Join 1,100+ business and technical leaders.