Hybrid / Intermediary Exchange
1.0.0 - CI Build United States of America flag

Hybrid / Intermediary Exchange, published by HL7 International - FHIR Infrastructure. This is not an authorized publication; it is the continuous build for version 1.0.0). This version is based on the current content of https://github.com/HL7/fhir-exchange-routing-ig/ and changes regularly. See the Directory of published versions

Exception Handling

After an originating system initiates an exchange, an exception could occur…

  • at the destination service


  • at an intermediary that is helping route the exchange.

This section describes a base set of conventions for reporting these exceptions.

Approach for conveying destination and intermediary exceptions

Destination-reported exceptions

Exception HTTP status codes generated by the destination are passed through unchanged by the intermediary to the originator.

Intermediary-reported exceptions

When an intermediary experiences an exception (including no HTTP response from a downstream actor) it SHALL:

  • Stop the process of routing the request
  • Return the associated HTTP status code

When an intermediary receives an exception reported by another intermediary or the destination, it SHALL pass the HTTP status code to the originator.

Note: This guide doesn’t restrict parties from arranging for an intermediary to perform validation or other error detection on behalf of the destination. In that event:

  • either the intermediary or destination SHALL return an exception status code for each exception that occurs
  • the intermediary MAY report errors it handles to the destination.


Situation HTTP Status Notes
Exceptions reported by an intermediary
Destination can’t be resolved 404 Not Found Indicates that the destination could not be determined based on the submitted FHIR service base URL
Attempt to connect to destination server timed out (with no response) 504 Gateway Timeout Indicates that a timeout occurred when trying to reach the destination server. Resource that the gateway was trying to connect to timed out
System error 500 Internal Error The server may not be able to generate an OperationOutcome in a system error situation
Exceptions reported by the destination
Submitted URL path returned Page/Resource Not Found 404 Not Found Generated by the destination, regardless of whether using direct connect or an intermediary. Intermediary passes through the status code and OperationOutcome if returned by the destination
Invalid request (e.g., bad query content) 400 Bad Request as above
System Error 500 Internal Error as above