This page is part of the Hybrid / Intermediary Exchange (v1.0.0: STU1) based on FHIR R4. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

Exception Handling

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

• at the destination service

  or

• 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.

Examples

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