You can use queries for synchronous requests, which includes REQUEST or RESPOND types of API actions. You would do this when you want to query data from your connection's system or respond with data from your own system to your connection's query. Either way, the system that requests the 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.
For any of these scenarios, you can check the related log for details after you receive a response. The related log object and ID is located in the Meta.Logs[].ID array (for the Redox Data Model API) in the body of the response. You can search for any of the log IDs in the dashboard or via the Platform API. Learn more about logs.
This is the best case scenario: Redox successfully processes and delivers your query to the intended endpoint, and the endpoint successfully accepts the request and returns results.
When this happens, you receive a 200 OK status from Redox and the body of the same response contains the requested data from your connection's EHR system. The fields and values present are specific to the data model or FHIR® resource requested.
Learn more about data models we support, including fields, requirements, and details for each one.
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.
{"Meta": {…"Errors": [{"Text": "Destination returned an error response.","Module": "Destination Response","DestinationStatusCode": 401,"Details": "Not authorized to access this patient."}]}}
{"resourceType": "OperationOutcome","issue": [{"severity": "error","code": "invalid","details": {"text": "Unknown search parameter name \"foobar\" for model \"Patient\"","coding": [{"code": "MSG_PARAM_UNKNOWN","system": "http://terminology.hl7.org/CodeSystem/operation-outcome","display": "Parameter \"foobar\" not understood"}]},"diagnostics": "Failed to execute FHIR search"}]}
The DestinationStatusCode from the recipient system may or may not match the Redox status code. It could be an EHR-specific code or a general HTTP status code. Either way, we don’t currently rely on the recipient's system status code to determine the Redox HTTP status code.
This is the response that doesn’t get past our doors unfortunately. Sometimes, your query fails within Redox, which means we fail to process it, and it doesn’t get delivered to the intended endpoint.
If the error occurs within Redox, you may receive any of these 4XX or 5XX HTTP status codes.
| Code | Description |
|---|---|
400 Bad Request | The request is formatted incorrectly or is missing required information. |
401 Unauthorized | Authentication failed. This means you need to refresh or regenerate your access token and try again. |
403 Forbidden or 404 Not Found | The request is missing the (a) POST verb; (b) designated endpoint; or (c) specified data model/resource after api.redoxengine.com (or api.ca.redoxengine.com for Canada). |
413 Payload Too Large | The payload sent exceeds the payload size limit of 10 MB. |
429 Too Many Requests | Your system has exceeded the rate limit of 7,500 requests per IP address for the current five-minute rolling window. Wait a few minutes then try initiating the request again. |
500 Internal Server Error | An unknown error occurred within Redox. |
502 Bad Gateway | The request was dropped within Redox. This can sometimes occur during brief periods when internal updates are being applied. |
504 Gateway Timeout | The request took too long to complete. Requests to Redox time out after a couple of minutes. |
For any of the 5XX errors, you can retry sending the request to see if the Redox issue is resolved. We recommend using an exponential backoff strategy between retries. If the error still persists though, submit a ticket via our Help Desk.
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.
If you successfully receive a synchronous request from your integration, your system should send back a 200 OK status with a response event 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 so that the provider can review your patient data before deciding on a new medication. So, the EHR system sends you a ClinicalDecisionsSupport request for more data. Your system successfully processes the request and aggregates results with the relevant data payload. 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 was not 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.