HTTP status codes: What they mean and how we use them

March 30, 2017
Julia Zehel -

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

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.IDMeta.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

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:

Implications

If you have questions about any of the information listed above, don’t hesitate to reach out at [email protected]. We’re happy to help you with any issues you’re having or provide extra support with your technical questions.

Subscribe for updates

Never miss an important Redox Changelog announcement. Sign up to have new posts emailed directly to your inbox.