User Event API failure protocol

This section covers the Failure Protocol when using the Moloco Commerce Media User Event API service. The protocol offers as seamless a manner as possible to preserve and recover lost data, depending on the specific reason for the failures.

📘

Note

This information may not cover all possible scenarios. Use this guide to handle unexpected issues, but consider it overridable depending on your specific situation. This guideline is subject to change as future releases and updates occur.

Protocol for Server-Side Issues (Moloco Issues)

If Moloco’s PostUserEvent API does not work as expected, the following protocol should be used. This protocol assumes that the response code of the call was 5XX. If the response code was 4XX, please see the Client-Side Issue protocol.

  1. Retry the call after a minimum 5-second delay.
  2. Further retries can be issued with exponential backoff, e.g., 10 sec, 20 sec, 40 sec, etc.
  3. If more than five retries fail contiguously, preserve the user event data rather than call the API for future events.
  4. Periodically reattempt the API with a predefined interval (e.g., 15 minutes).
  5. Restart using the API once you get successful responses.
  6. See the “Resending User Events” section for ways to resend failed user events.

Protocol for Client-Side Issues

In the case the client side was not able to call our API or received a 4XX response for the API call, the following protocol should be used.

  1. If the API call response code is 429, limit the client side’s QPS by buffering the API calls.
  2. For any other 4XX response, examine the API for authorization or malformation issues.
  3. Preserve any user events that you were not able to send us via the API.
  4. See the Resending User Events section for ways to resend us the failed user events.

Resending User Events

If the number of lost events during the downtime is not excessive consider using the same event API to resend the events to Moloco. We recommend the following actions when resending events:

  • Speak with your Moloco team before resending the lost user events.
  • Start with a low QPS to avoid affecting real time operations. A QPS less than 20% of your peak time QPS is recommended.
  • Resend lost events during hours with minimal real-time traffic.

To manage large scale backfills please consult with your Moloco team for assistance and planning.