In this final section of our Get Started guide, we will go over some tips and best practices to using the Bloomreach Engagement API.

📘

This section will be continuously updated with more tips and best practices.

Best practices

Use batch commands for pushing multiple things at once.

You might often get to a point when a single customer journey consists of multiple events that you want to send through the API. For example, a customer purchases 4 items. In terms of events, this would at the very least consist of 1x purchase + 4x purchase_item + 1x customer update. These are 6 different commands to send - just 1 request by sending them in a single batch!

Error handling

When working with the API, you might encounter errors and it is essential to know how to react correctly depending on the error. It is best practice to implement error handling into your code where possible.

Errors with all API requests

Error

Description

HTTP 200 with success = false

Invalid request. Retrying will not help, you need to look for a mistake in your request.

HTTP 400

Invalid request. Retrying will not help, you need to look for a mistake in your request.

HTTP 403

You do not have the necessary permissions for this request. To correct, allow required permissions, or check if you are using the correct destination project.

HTTP 500

API is unavailable. Retrying later could help, please implement Exponential backoff for retries.

HTTP 429

You are over the rate limits. You should retry the request(s) later with an Exponential backoff and send subsequent requests at a slower rate.

We have described some specific error situations with some of the requests (e.g. batch commands), where applicable, and you can find these in the Error handling section under the respective requests.