5.3 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. Contact your Moloco representative if you cannot resolve the issue after following this guide.



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 Customer 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

Please follow one of the methods to send user events that were not submitted during real-time operations.

If the number of lost events during the downtime is not excessive, consider using the same event API to resend them. This option should be the go-to option whenever possible since it should have a lower overhead than dealing with the CSV file in option 2 for both parties. However, the following rules should be followed.

  • The resend must be done with a low QPS to avoid affecting our real-time operations. Please use a QPS less than 20% of peak time QPS.
  • We strongly recommend resending lost events during hours with minimal real-time traffic.

If the number of lost events exceeds what is reasonable to be sent via the API, or it is infeasible to send the events via the API for whatever reason, create a CSV file with the event information. Each line in the CSV file should have the following format, and each line should correspond to one event. All fields should match the requirements for the PostUserEvent API.

  • Any optional fields can be omitted with consecutive commas, e.g. field_a,,field_c,field_d.
  • Nested fields should be added within the braces {} with each inner field separated by a comma.
  • Array fields should be added within the brackets [] with each element separated by a comma.
  • Always end the line with a comma after the last field.
  • Please adhere to the API documentation reference.

Example line in CSV format:

1234, PURCHASE, 1617870506121, SITE, 5678, {IOS, 15.3.1, , 89ab, iPhone 12 Pro, , en}, [{aaa, {KRW, 1000}, 1}, {bbb, {KRW, 500}, 2}], {KRW, 2000}, , 11111, , ,