Error handling for the thematic API - Bloomreach Experience - The Headless Digital Experience Platform Built for Commerce

Error handling for the thematic API

What happens when there's an error?

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.

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


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:

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

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. shows site visitors a Thematic Page called Gorgeous Red Cocktail Dresses. shows site visitors a 404 error because the correct theme name uses the plural form of dress: 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.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?