Responding to queries

You can use queries for synchronous requests, which include the REQUEST or RESPOND types of API actions. You'd do this when querying data from your connection's system or responding with data from your own system to your connection's query. Either way, the system that requests data waits for a response from the endpoint the query is sent to.

Like everything else in life, some requests work out and others don’t. We’re happy to let you know the fate of your request either way, and we have some details about each scenario below.

For queries, you receive one response with two parts: the HTTP status code from Redox and the results of your query from the endpoint.

There are three scenarios for synchronous responses.

Best case scenario: Redox successfully processes and delivers your query to the intended endpoint, and the endpoint successfully accepts the request and returns results.

If so, you receive a 200 OK status from Redox. The response body contains the requested data from your connection's EHR system. The fields and values present are specific to the data model or FHIR® resource you sent.

Occasionally, Redox successfully processes and delivers your request, but an error occurs within your connection's EHR system, so it fails to accept the query.

If this happens, you still receive a 200 OK status from Redox, but the body of the response contains an array populated with error data: Meta.Errors[] array (for the Redox Data Model API) or issues[] array (for the Redox FHIR® API). At a minimum, a Text field from Redox provides the error message details. But you may see additional fields with data from your connection's system depending on the failure type. If present, the DestinationStatusCode contains the failure status code and the Details field contains information about the error as determined by your connection's system.

1
{
2
   "Meta": {
3
     …
4
     "Errors": [
5
       {
6
         "Text": "Destination returned an error response.",
7
         "Module": "Destination Response",
8
         "DestinationStatusCode": 401,
9
         "Details": "Not authorized to access this patient."
10
       }
11
     ]
12
   }
13
 }

1
{
2
		"resourceType": "OperationOutcome",
3
		"issue": [
4
			{
5
				"severity": "error",
6
				"code": "invalid",
7
				"details": {
8
					"text": "Unknown search parameter name \"foobar\" for model \"Patient\"",
9
					"coding": [
10
						{
11
							"code": "MSG_PARAM_UNKNOWN",
12
							"system": "http://terminology.hl7.org/CodeSystem/operation-outcome",
13
							"display": "Parameter \"foobar\" not understood"
14
						}
15
					]
16
				},
17
				"diagnostics": "Failed to execute FHIR search"
18
			}
19
		]
20
	}

Worst case scenario: Your connection's response doesn’t get past our doors, unfortunately. Sometimes, your query fails within Redox, which means we fail to process it, and we don't deliver it to the intended endpoint.

If the error occurs within Redox, you may receive a 4XX or 5XX HTTP status. Review HTTP errors.

When you receive a synchronous request from your integration, we wait for you to send back a response with the results of their request. Then, we return it to your integration in the format indicated in their request.

When you successfully receive a synchronous request from your connection, you should send back a 200 OK status with a response type that matches the request.

Here’s an example: Your connection’s EHR system triggers an alert when a provider wants to order a new medication for a patient. But before placing the order, the provider wants to review the patient's data before deciding on a specific medication. So, the EHR system sends a ClinicalDecisionsSupport request for more data. Your system successfully processes the request and aggregates results with the relevant data. You respond to Redox with a 200 OK status and the ClinicalDecisionsSupport.Response data model.

That’s the kind of response everyone hopes for.

However, failures can’t always be avoided. There are two scenarios for failed deliveries to your system.

If we don’t hear back from you within a couple of minutes, the original request times out, and we let the initiating system know that their request wasn't received. If they want to try again, they can retry sending from their system.

If an error occurs in your system that prevents you from successfully receiving the synchronous request from us, your system should send back the relevant 4XX or 5XX HTTP status code and a response with the relevant array populated: the Meta.Errors[] array (for the Data Model API) or the issues[] array (for the FHIR® API) populated. This array should contain an error object with the type of failure and corresponding details. At a minimum, a Text field should provide the error message details. We send the failed status code and the response with the errors back to your integration so they can check out the details in a log on their dashboard.