REQUEST

In order to request data from a destination system via Redox (two-way), you should first set up yoursource configuration as described in Initiating Requests (Source) and initiate your requests as described there.

You can request data from one destination at a time.

Response Handling

Responses returned for two-way workflows, when the initiating source system is expecting a response from a destination system, reflect both the status of the request and also carry details related to results of the request.

✅ Successful Request

A successful request will return with a 200 HTTP status code and an empty Meta.Errors[] array.

Note: A 200 response code alone does not indicate successful processing of the request by the destination system. More on this below.

CodeTitleDescription
200SuccessRequest was successfully received and processed by Redox

Further, the response body will contain additional reference information about the request within the Meta object:

PropertyDescription
Meta.Logs[].IDThis value can be used to look up a Log entry in the dashboard via Logs Search.
There can only be one Log entry for a synchronous request.

Finally, the results of the request are returned within the remaining top-level keys of the response body. These keys and the values they contain are specific to the Data Model and Event Type requested.

In our documentation, response bodies are listed as -Response event types. More details on this here: Data Models & Event Types

🔴 Unsuccessful Request

Requesting data from a destination system requires a synchronous, two-way transfer of data to send the initial request to the destination and then return the destination’s response. This means that errors returned for the request can either be errors within Redox or the destination system.

Regardless of status code, if there is an error object present in the Meta.Errors[] array, then something went wrong with your request.

Determining Failure Mode

The workflow for each synchronous request is as follows (viewable in detail on the Logs page of the Dashboard):

  1. Your (source) system initiates the request
  2. Redox processes the outbound request and sends to the Destination
  3. Destination system receives and responds to the request
  4. Redox processes the Destination system’s response and returns response to your (source) system
  5. Your (source) system receives the response to your request

Each downstream system reports errors differently:

Downstream System Status Indicator
RedoxHTTP Status Code & Meta.Errors[]
Destination SystemMeta.Errors[]

Redox Errors

Response status codes returned for these requests refer to Redox processing status. As such, 4XX and 5XX failure response status codes returned are the same as those returned for requests that SEND:

CodeTitleDescription
400Bad RequestRequest is formatted incorrectly or is missing required information.
401Unauthorized
Authentication failed. Refresh or regenerate your access token and try again (see Initiating Requests (Source) for info on how to do so).
413Payload Too LargePayload sent exceeds the payload size limit of 10mb.
500Internal Server ErrorAn unknown error occurred within Redox.
500Bad GatewayThe request was dropped within Redox. This can sometimes occur during brief periods when internal updates are being applied.
504Gateway TimeoutThe request took too long to complete. Redox API requests timeout after 120 seconds.

For 5XX level errors, your system should retry the failed request. If these errors persist, please reach out to Redox support.

Additional error data may also be retured via the Meta.Errors[] array.

Destination Errors

If there is a destination error, it will be included within the Meta.Errors[] array returned in the response. If the destination returned it’s own status code, it will also be included within the error object returned.

Meta.Errors[]

Meta.Errors[] will be included in the response body and contains error objects pertaining to the errors that occurred. Specifically, some fields that may be returned within each error object:

FieldDescription
TextError message recorded within Redox
DestinationStatusCodeStatus code returned by the destination system
DetailsError message returned by the destination system

Here’s an example of a 401 response returned from a destination system:

{
   "Meta": {
     …
     "Errors": [
       {
         "Text": "Destination returned an error response.",
         "Module": "Destination Response",
         "DestinationStatusCode": 401,
         "Details": "Not authorized to access this patient."
       }
     ]
   }
 }