Error handling

A request that fails is typically returning an OperationOutcome.

Returned information

This impacts on error management as the information returned describing the error depends on the tier where the error occured.

  1. First thing to check is the HTTP status, e.g. HTTP/1.0 503 Service Unavailable. The HTTP status returned is the most importent information about the outcome of the request. Anything in the 200 range indicates a success, and anything else a failure.

  2. Next thing is to check is what kind of data the HTTP body contains by looking at the content type header field. Content-Type: "text/html" would for example indicate that an error occured at the transport layer beacuse a FHIR response SHALL be tagged as application/fhir, e.g. Content-Type: "application/fhir+json; charset=UTF-8". A non FHIR response should be treated as a system error.

  3. The third thing to check is what type of FHIR resource the response body contains. This would in most cases be either nothing, an OperationOutcome, a Bundle or the requested resource. An error will however always result in an OperationOutcome independent of the requested outcome. The last thing when it comes to errors is to check what the OperationOutcome says about the error. How to interpret the OperationOutcome is covered in the next section.

The OperationOutcome resource

OperationOutcome is a very versatile resource that can handle information in many ways. This can make it a daunting task to build a generic error handling mechanism on the receiving end. Below is a summary of recommended principles when transmitting data as an OperationOutcome to make this task a little easier. It is important to understand that the FHIR component relies on backend systems and run on top of a routing layer. The principles can therefore not be guaranteed.

In the text below, a successful request is one with an HTTP status in the 200 range. A failed request is one with an HTTP status in the 400 or 500 range.

  • issue.severity SHALL be set to one of the 4 IssueSeverity codes. In case of a failed request issues that are the cause of the failure SHALL be tagged as "error" or "fatal". Issues tagged as "information" or "warning" are not the cause of the failure.

  • issue.code SHALL be set to one of the IssueType codes. The code SHOULD give a good indication of the issue type in most cases, but it is not guaranteed.

  • issue.details SHALL include an error code and a error message.

  • details.coding.code SHALL contain a code that defines what the issue is about. A code SHOULD be in the format n-nn-nnn, for example: 2-26-104.

  • details.coding.display SHALL contain the display text from the code system. The display text MAY contain parameters (dynamic parts) that are populated when the issue occurs.

  • diagnostics MAY be populated to facilitate in depth error investigations.

Transactions and Bundles

Bundles can be used for handling multiple resources within one transaction. In this scenario the transaction SHALL return a successful result only if all actions in the transaction are accepted by the server. Otherwise the transaction SHALL be rejected.

A failed transaction SHALL result in a HTTP status in the 400 or 500 range and in one single OperationOutcome instead of a Bundle. The element OperationOutcome.issue.expression SHALL contain information about which resource and element in the request Bundle that raised the issue. See FHIR Transaction processing rules.

Exceptions

Routing error

Errors that occur at routing level and never reaches the FHIR component will result in a non FHIR response.

It may look like this.

HTTP/1.0 503 Service Unavailable
Connection: close
Content-Type: text/html
 
<html>
<head>
</head>
<body>
<div>
<h1>Application is not available</h1>
<p>The application is currently not serving requests at this endpoint. It may not have been started or is still starting.</p>
</body>
</html>

FHIR parsing error

Servers may be based on FHIR libraries with built in error handling for low level communication, such as the HAPI FHIR library. Errors caught by HAPI will result in an OperationOutcome that follows another structure than the one described above.

It may look like this.

HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json; charset=UTF-8
 
{
"resourceType": "OperationOutcome",
"issue": [ {
"severity": "error",
"code": "processing",
"diagnostics": "Multiple values detected for non-repeatable parameter 'code'. This server is not configured to allow multiple (AND/OR) values for this param."
} ]
}