HomeEngagementContentDiscoveryOther resources
API reference

Error handling for the thematic API

If there's an error in an API call, then your customer's browser behaves the same way that it does when it attempts to load a category page that doesn't exist. Bloomreach doesn't redirect your customer to the homepage nor record the timeout parameter.

Common errors are related to timeouts or a theme name that doesn't exist.

📘

Tip

We recommend that you redirect HTTP errors to your site's home page.

Timeouts

We recommend that you set the timeout for your thematic pages to 2 seconds.

If there's a timeout during a thematic page load, then we recommend that you redirect your customer with a HTTP 302 response code to your site's home page. Append this specific tracking parameter redirected the URL: ?_thto=1. This parameter serves a few purposes:

  • It ensures that your customers always receive a page load.
  • It collects data to assist Bloomreach in troubleshooting timeouts.

For example, let’s say that the following page encounters a timeout error when loading:

http://www.example.com/shop/gorgeous-red-cocktail-dresses

Then the site redirects the customer to the home page with a 302 response code, and uses the following URL:

http://www.example.com/?_thto=1

Your Bloomreach representative can work with you to determine the ideal timeout setting for your requirements.

Bad theme names

If a theme name doesn't exist, then Commerce Organic sends a 404 error. For example, Dresses by Colette assigns gorgeous-red-cocktail-dresses as the theme name for one of its Thematic Pages.

  • http://www.example.com/shop/gorgeous-red-cocktail-dresses shows site visitors a Thematic Page called Gorgeous Red Cocktail Dresses.

  • http://www.example.com/shop/gorgeous-red-cocktail-dress shows site visitors a 404 error because the URL uses dress instead of dresses.

As with all other HTTP errors, we recommend that you redirect the error to your site's home page.

API Response with Zero products (for JSON Thematic Pages)

For JSON thematic pages, if you receive an API response and the number of products that match the theme is 0, you will have to set up behavior so that the page triggers a timeout.

In the case of HTML thematic pages, this is handled by the 4xx error which triggers a timeout, so this does not apply if you are using the HTML implementation.