HTTP status codes: What they mean and how we use them
Mar 30, 2017
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 was wrong with the request. Usually, this means that a required field is missing. For example, if the device message is missing Device.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"
}
]
}
}
401 Unauthorized
Redox will return a 401 response when authentication to the Redox API fails.
A reason will be sent in plaintext:
Invalid source secret
This source is not authorized.
Source not found
$ curl \
-X POST https://api.redoxengine.com/auth/authenticate \
-H "Content-Type: application/json" \
-d '{"apiKey": "<API KEY>", "secret": "<SECRET>"}'
Invalid source secret%
404 Not Found / 403 Forbidden
Redox will return 403 and 404 responses if the API request does not use the POST verb, 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 problem with a particular patient's email address, handle that on your side, communicate it us via e-mail, and send a 200 to back to the API.
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.
If you have questions about any of the information listed above, don't hesitate to reach out at hello@redoxengine.com. We're happy to help you with any issues you're having or provide extra support with your technical questions.