When API Messages Fail: Ocean’s API Retry Logic and Troubleshooting

What It Is

While there are many advantages to RESTful APIs, one downside is that if a call is unsuccessful, there is by default no memory of the failed attempt. For system-system API integrations, particularly in healthcare, this can be dangerous in that it could lead to information loss and process disruptions between systems.

To address this issue, Ocean has a built-in automated retry capability for all direct Open and FHIR-based Ocean API integrations. This Ocean service will resend any webhook notifications that do not receive a 20X-class (e.g 200, 201) status response code once per hour for up to four days.

How It Works

This service will be operated from the Ocean Cloud Connect module. Cloud Connect manages a queue of all webhook notifications that are funneled through it until they are successful or time-out.

  • Successful calls are removed from the queue.
    • The first unsuccessful API call will trigger an email alert containing the name of integration and error message encountered by Ocean, which will be sent by email to the Ocean Site's 'Clinical Administrator / Ocean Support Contact' email address specified in the Site Account settings.
    • Ocean will retry the call to the endpoint several times in the first hour. If unsuccessful, Ocean will try once an hour.
    • Every 24 hours, Ocean will send an email alert to the 'Clinical Administrator / Ocean Support Contact' to update them that the issues are still not resolved.
    • If the integration subsequently accepts a message from Ocean or if its settings are resaved, it will cease to appear in the daily email alert.
    • After 96 hours, Ocean will abort attempts to reach the endpoint and will send a final email alert stating that the maximum number of retries has been reached.

What You Need To Do

  • Ensure that the email address(es) of the individual(s) most responsible for the integration is/are included in the Ocean Site's 'Clinical Administrator / Ocean Support Contact' field. This may be the clinic's IT manager and/or vendor's point of contact; They do not have to be a user on the Ocean Site.
    • Multiple email addresses can be specified in the field - simply separate each email address using a comma.
  • When an email alert is received from Ocean, it generally indicates an issue with the receiving system's endpoint, not with Ocean. The first step to take is investigate the health of the receiving system's endpoint prior to reaching out to the OceanMD Support team.
  • Common issues encountered include:
    • Expired certificates.
    • Unplanned system downtime.
    • The receiving system's endpoint is unsure of how to process the message it has received.
  • If assistance is needed or it appears to be an Ocean-related issue, please submit an incident report to the OceanMD Support Team. In your report, be sure to include:
    • Ocean Site Number
    • Ocean Environment (i.e., test.cognisantmd.com, staging.cognisantmd.com, or ocean.cognisantmd.com)
    • A description of the investigation performed to date to assess any issues with the receiving endpoint.
    • A complete screenshot of the Ocean email alert.
Have more questions? Submit a request