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:

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 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. Varies based on the specific request
201 Created Indicates the submitted resource was accepted. Display a message to the user indicating the resource was successfully submitted.
400 Bad Request This indicates that the submitted request is invalid. For example, the URL is malformed, the query parameters are badly formatted or do not match the required data type. Typically, this indicates an error with the software design of the client system, but in cases where the client does not validate inputs (e.g. dates) before submission, it is possible that allowing the user to correct search parameters could result in a successful response. Display the message associated with the OperationOutcome to the user and also provide information for how to contact system support for the client software. The OperationOutcome.issue.diagnostics and location should be made available as well.
401 Unauthorized Indicates the request has been made without the appropriate authorization token. 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. The client system should re-authenticate and re-transmit the request once a new token is received
403 Forbidden The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort 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
404 Not found This will only be returned in the event of a specified resource does not exist. 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
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. 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
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. 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 that the server encountered an Internal error during the process of response message
503 Service Unavailable Indicates that the services has been temporarily taken down (on purpose) 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 Indicates that one server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser.


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.

Simplifier link for the profile: LRA General Response OperationOutcome

idΣ0..1string
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
text0..1Narrative
contained0..*Resource
extensionI0..*Extension
modifierExtension?! I0..*Extension
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
severityS Σ1..1codeBinding
codeS Σ1..1codeBinding
id0..1string
extensionI0..*Extension
id0..1string
extensionI0..*Extension
systemS Σ0..1uri
versionΣ0..1string
codeS Σ0..1code
displayS Σ0..1string
userSelectedΣ0..1boolean
textS Σ0..1string
diagnosticsS Σ0..1string
locationΣ0..*string
expressionΣ0..*string

The complete list of error codes returned within the OperationOutcome is defined in LRAValidationCodes