Asynchronous requests

Asynchronous requests are primarily used for one-way, event-based data streams where systems SEND or RECEIVE data. You can think of these like CRUD type of requests you want to send to or receive from your connection's EHR system.

Recoverable messages

For asynchronous requests, we use recoverable messages to ensure delivery. We save these messages into highly durable queues so that they can survive restarts or other failures. We don't respond with a 200 OK status unless we successfully saved the message in a highly durable queue first.

Read about our business continuity and disaster recovery plan.

Sequencing of asynchronous events

Your request is delivered via Redox to the desired integration using a first-in, first-out (FIFO) method. We work to maintain the order of requests to one of your integrations as they were sent. 

One caveat to that, though, is that sometimes messages are processed in parallel prior to being sent in FIFO order. Because of this, the message ID and transmission ID shouldn’t be used to sequence requests sent to a particular endpoint, especially when they rely on different data models or FHIR® resources. Instead, you should use the timestamp for when the data arrived at the endpoint to sequence it against other asynchronous requests.

If failures happen during processing, we pause the queue for the intended endpoint so that we can maintain FIFO delivery after the issue is resolved.

Meanwhile, we send a notification to the sender or receiver, depending on where the failure occurred. Either way, the notification goes to the Alert Email, which is listed in the Organization Profile of the Redox dashboard.

Responses to SEND

Some packages don’t get to their intended destination. Amazon knows this well. 

Sometimes your asynchronous requests also don’t get to their intended endpoint(s). The good news is that we can let you know whether your request arrived safely. Keep in mind that since asynchronous requests are one-way, you won’t get a response back from your connection's system (much like Amazon doesn’t get thank you packages for successfully delivered orders). 

Any responses to asynchronous requests are from Redox specifically about your outgoing request. And if your one request went to multiple endpoints, you still receive only one overall response to your asynchronous request. Check out the details about each scenario below.

Successful response

If Redox successfully accepts your request, you receive a 200 OK status with an empty Meta.Errors[] array (for the Redox Data Model API) or issue[] array (for the Redox FHIR® API) in the body of the response.

This does not mean though that the request was successfully delivered to the intended endpoint. It only means that we received the request, saved it to a highly durable queue, and are ready to process it before delivering to the intended endpoint(s). 

Later, if you want to know for certain whether your request was successfully processed and delivered, you can check the status of the related log. Learn more about logs

An important distinction between responses and logs is that you only receive one response to a request for multiple endpoints, whereas Redox creates a log for each endpoint. So if you send one request to 10 endpoints, you receive one response with 10 log objects and IDs in Meta.Logs[].ID array.

Unsuccessful response

On occasion, Redox can’t process a request because of an issue with the request or within Redox itself. If this happens, you receive a 4XX or 5XX HTTP status code and a response with the an array in the body populated: Meta.Errors[] array (for the Data Model API) or the issue[] array (for the FHIR® API). These arrays contain an error object with the type of failure and corresponding details. At a minimum, a Text field provides the error message details.

As for the HTTP status codes, you may see any of these: 

CodeDescription
400 Bad RequestThe request is formatted incorrectly or is missing required information.
401 UnauthorizedAuthentication failed. This means you need to refresh or regenerate your access token and try again.
403 Forbidden or 404 Not FoundThe request is missing the (a) POST verb; (b) designated endpoint; or (c) specified data model/resource after api.redoxengine.com.
413 Payload Too LargeThe 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 ErrorAn unknown error occurred within Redox.
500 Bad GatewayThe request was dropped within Redox. This can sometimes occur during brief periods when internal updates are being applied. Try sending the request again.
502 Bad GatewayThe request failed due to Redox updates. This rarely happens, but if it does, you should try sending the request again.
504 Gateway TimeoutThe request took too long to complete. Requests to Redox time out after a couple of minutes. Try sending the request again.

We recommend that your system have queuing capability for your outgoing requests to Redox in case of any kind of failure. This way, your system can queue any subsequent outgoing requests until the issue is resolved.

Contact us

For any of the 5XX errors, you can retry sending the request to see if the Redox issue is resolved. If the error still persists though, submit a ticket via our Help Desk.

Responses to RECEIVE

When you receive a data payload from your integration, we rely on you to send us back an HTTP status code to let us know whether your system received it successfully. We wait for your response before deciding what to do next. 

Successful receipt

If you successfully receive an asynchronous request from us, your system should send back a 200 OK status with an empty Meta.Errors[] array (for the Redox Data Model API) or issue[] array (for the FHIR® API) in the body of the response. This response means that your system has processed the most recent data and is ready for the next payload. We proceed with sending your next asynchronous data payload. 

Unsuccessful receipt

If unable to receive an asynchronous request, your system should send back to Redox the relevant 4XX or 5XX HTTP status code and a response with the relevant array in the body populated: Meta.Errors[] array (for the Redox Data Model API) or the issue[] array (for the Redox FHIR® API). 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.

What your integration doesn't know

The failed response comes to us, but we don't pass it back to your connection's system. Your connection won't know that your system failed to receive their request.

It's possible to set up custom notifications if you're on our highest platform tier, however. Talk to a Redoxer if you want to know more.

If you send a failed HTTP status code in response to an asynchronous request from us, our next action depends on the type of environment your endpoint is in. 

For a production environment, we retry sending the request to you after a brief pause and we pause the queue.

For a staging or development environment, we retry sending the request after a brief pause, but we don’t pause the queue of asynchronous requests from your integration.

Non-critical errors

For non-critical errors, we expect that you send back a 200 OK status prior to performing data validation or after finding an error that can be resolved at a later time. This way, we don’t pause your data for production environments and your development/staging environments can proceed with business as usual. This option ensures continuity in your data delivery so that your data flow doesn’t get hung up on a single troublesome data payload.

If you do identify a non-critical issue with an incoming request, we recommend that you log an error in your system and submit a ticket via our Help Desk if you need help resolving it.

Alternatively, if you're experiencing downtime or another critical error, we recommend that you send a 4XX or 5XX status to initiate pausing on our end so that none of your data is lost while you work to resolve your system.

Automatic retries

The process for automatic retries occurs differently based on the environment type.

Production environments

If an asynchronous request fails in a production environment, we retry the failed request for you until it succeeds. Also, we pause the queue for subsequent asynchronous requests. This means that other asynchronous requests can't be sent until the failed request succeeds. Our Integration team receives notifications if the queues pile up so they can review and resolve any processing failures. 

Failed test requests for production

We ignore delivery failures for test requests. This means we don’t automatically retry or pause the queue when test requests fail sending to a production environment. 

But let’s explain how we retry your failed request with that analogy of a mail carrier delivering a physical package: 

The mail carrier rings the doorbell the first time, but no one answers. They wait a few seconds, then try ringing the doorbell again. There’s still no answer, but this is a determined—but polite—mail carrier. They wait a little longer before retrying a third time. Even then, the mail carrier doesn’t give up. They keep ringing the doorbell, but they wait a little bit longer between each try, so as to not be obnoxious while being persistent. Finally, the door opens, the receiver accepts the package, and the mail carrier continues on to deliver the next package. 

In Redox terms, we follow the same pattern: waiting a few seconds before retrying, then steadily increasing the wait period until it becomes a fixed wait of a minute or two between requests. Retries continue every couple of minutes until the receiving endpoint acknowledges they received the data, or until we manually pause the request. 

Unexpected pauses

Retries may stop unexpectedly if we receive a different error code from the recipient system that initiated the request. We review these types of alerts daily to see if we need to manually intervene. If so, we reach out to the recipient's team to resolve issues.

Custom notifications

We're all about that "never surrender" life, but we do let you know if we're having trouble delivering a request after our third failed attempt. We notify you via the email address listed in your alert email, which is in the Organization Profile page of the dashboard. Make sure that email address is up-to-date so that we can let you know when there's trouble in paradise—and when we've found paradise again by successfully delivering the request.

If you would like, we can set up more custom notifications for you, whether via email or Slack. For example, you can receive notifications for each endpoint that fails to accept one of your requests. Submit a ticket via our Help Desk to talk about your notification options.

Development or staging environments

If an asynchronous request fails in a development or staging environment, we still retry the failed request, but we don’t pause the queue for subsequent asynchronous requests. This means that other asynchronous requests can continue sending.

Failed test requests for development or staging

We ignore delivery failures for test requests. This means we don’t automatically retry when test requests fail sending to a development or staging environment. 

Manual retries

Manual retries can be done by navigating to the related log of the request you want to re-send. You can perform a manual retry on any request you like, whether it be a test request that didn’t deliver, a request that Redox failed to process, or even a successful request that you want to send again. Learn how to initiate a manual retry.