User Event API Error Categories

This guide provides an overview of the various error codes you may encounter when using our User Event API, along with a description of the error and recommended actions.

The payload of the error response of the User Event API is a JSON-serialized grpc status. Therefore, if you want to know what the code in the response means, you can refer to this document: https://grpc.io/docs/guides/status-codes/. However, when an error occurs, our service returns the http status code matching the grpc code along with the error message. Therefore, you only need to look at the http status code and the message field in the payload.

{
  "code": 3, // Ignore
  "message": "page_id is empty",
  "details": [] // Ignore
}

Below is a table of HTTP error codes, their meanings, examples of errors, and how to mitigate them.

🚧
This is not a full list of error messages. If you have questions about an error message that is not documented in this list, please contact the Customer Engineering team.

HTTP Status	Meaning	Example messages	Mitigation
400 (Bad Request)	A client sends a malformed request.	no available valid identifier to construct Moloco advertising ID	Fill at least one of the user identifiers: - `user_id` - `device.persisent_id` - `custom_id`
		missing `search_query`	Fill the `search_query` field
		missing `page_id`	Fill the `page_id` field for PAGE_VIEW events.
		invalid item: either id or item_group_id must be set	Fill the `items.id` or `items.item_group_id` for items in the following event types: - ADD_TO_CART - ADD_TO_WISHLIST - ITEM_PAGE_VIEW - PURCHASE
		invalid timestamp	Check if the timestamp is unit time in milliseconds since UNIX Epoch ((e.g. 1736402704121 as of now) and it’s not a future time
		device os must contain ios or android for the app channel type	Specify “ios” or “android” in `device.os` field
429 (Too Many Request)	Too many requests comes from the user.	request denied by throttler, try again later	This usually occurs if you have set the same identifier for all or a subset of users (anonymous aka non logged-in users). As a reminder, each user (logged-in or anonymous) should be assigned an unique identifier. For logged-in users, please fill an unique identifier in `user_id`. For anonymous users, please use `device.persistent_id` as described in this guide.
500 (Internal Server Error)	Server can’t process requests by internal errors.		This could occur transiently. If it occurs too frequently, please contact the Customer Engineering team.

🚧This is not a full list of error messages. If you have questions about an error message that is not documented in this list, please contact the Customer Engineering team.

🚧
This is not a full list of error messages. If you have questions about an error message that is not documented in this list, please contact the Customer Engineering team.