HTTP Status Codes

When using our API, you may sometimes run into HTTPS status codes. Since status codes are an important way our API communicates, we want to clearly document what HTTP status codes the API can return, when they can come up, and what applications should do when they encounter each response.

We also want to use this page to share what we expect from webhooks.

Response Codes Returned by the Redox API

A 200 response indicates a successful request to Redox.

If the message has been sent to health systems and no response is needed, this simply indicates that the data model was valid and subscriptions were set up correctly.

If the health system needs to respond, 200 will be sent along with relevant response data, which may include errors. For example, in ClinicalSummary Query, the health system may be down or there may be no documents available for the patient. This will be a 200 response with a Meta.Errors array.

{
  "Meta": {
    "Errors": [
      {
        "ID": 531806,
        "Text": "Something went wrong retrieving the document list. Please contact Redox Support. Could not find any documents.",
        "Type": "query",
        "Module": "Send"
      }
    ]
  }
}


400 Bad Request

A 400 Status code indicates that the message was received, but something went wrong with the request. Often, this means that a required field is missing. For example, if the device message is missingDevice.ID, Meta.Errors will inform you of that.


{
  "Meta": {
    "DataModel": "Device",
    "EventType": "New",
    "Message": {
      "ID": 41962259
    },
    "Source": {
      "ID": "aed02b8f-f001-491d-a521-1d757af59bef",
      "Name": "redox-sample"
    },
    "Errors": [
      {
        "ID": 531829,
        "Text": "Required field missing - Device.ID in Device:New",
        "Type": "message",
        "Module": "DataModels"
      }
    ]
  }
}

If the destination system returned an error, Redox will return a 400  response with additional detail in the Errors  array of the response body:

{
  "Meta": {
    "DataModel": "Device",
    "EventType": "New",
    "Message": {
      "ID": 41962259
    },
    "Source": {
      "ID": "aed02b8f-f001-491d-a521-1d757af59bef",
      "Name": "redox-sample"
    },
    "Errors": [
      {
        "ID": 531829,
        "Text": "Destination returned an error response.",
        "Type": "transmission",
        "Module": "Destination Response",
        "DestinationStatusCode": 401,
        "Details": "Not authorized to access this patient."
      }
    ]  
  }
}

401 Unauthorized

Redox will return a 401 response when authentication to the Redox API fails with a plain text message of Invalid request .


curl -X POST https://api.redoxengine.com/auth/authenticate \
    -H "Content-Type: application/json" \
    -d '{"apiKey": "<API KEY>", "secret": "<SECRET>"}'

404 Not Found / 403 Forbidden

Redox will return 403 and 404 responses if the API request does not use the POSTverb, or if the/endpoint or /query are not used.

500 Internal Server Error

Redox will return a 500 response when an unexpected error occurs in our system. Our automated pager will notify us instantly when this happens, but regardless, please reach out if you receive one.

How Redox Handles Response Codes from Your Application

200 OK

A 200 response from your application indicates that everything is OK. We wait for a 200 response before sending the next message. If we receive a status code >= 400, we will pause before sending you any more transmissions and retry the last one that failed.

Under the hood

For each of your destinations, there are multiple “subscription” queues. When get a response code >= 400 is received, the following happens:

  • The subscription queue for the particular transmission being sent is paused.
  • The failed transmission goes onto a subscription-specific retry queue.
  • Redox on-call engineer is paged.
  • When the retry succeeds, the normal queue is un-paused.

Implications

  • Avoid sending response codes over 400 back to Redox, unless you would like Redox to stop all traffic to your destination. For example, if you have a non-critical error, send back a 200 and log the error on your application. If you believe there is intervention needed, please reach out Redox support via support@redoxengine.com, the support phone number, or our Public Slack channel.
  • Use the pausing to your advantage. If you are experiencing a downtime, the pause is designed to make sure you don’t miss any messages.