This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Monitoring and troubleshooting

This page describes how to get information about errors that have occurred in catalog and user event imports, and other Retail API operations.

For help with setting up alerts, see Setting up alerts.


Providing accurate catalog information and user events to the Retail API is important to getting the highest quality results. Monitoring and understanding the source of errors helps you find and fix any errors in your site.

Seeing aggregated integration errors

To see the aggregated errors generated by your data upload processes and prediction or search requests, use the Monitoring tab on the Monitoring & Analytics page.

This page displays all errors for the Retail API. You can view errors related to the product catalog, user events, Recommendations AI predictions, Retail Search results, and models. The system also logs errors from imports, such as a malformed line in your Cloud Storage file. The system logs up to 100 errors per import file. You can define the time period for which errors are displayed and filter based on the error type.

You can click an individual error to see the logs for that error in Cloud Logging.

You can open individual error logs by expanding that log. Error logs provide more detail about the request, including the request and response payloads and error details. This information can help you determine where the erroneous method call is located in your site.

For invalid JSON errors, you can get more information about the issue by expanding the status field.

Seeing status for a specific integration operation

You can see status for a specific integration operation by using the integration activity panel:

  1. Go to the Retail Data page in the Google Cloud Console.

    Go to the Data page

  2. Click View Import Activity on the button bar to open the Import Activity panel.

    You can inspect errors for specific integration operations.

  3. Click View logs in the Detail column of any operation with an error to inspect its log files in Cloud Logging.

Error types

  • MISSING_FIELD: A required field value is not set; for example, a catalog item is missing its title.
  • INVALID_TIMESTAMP: The timestamp is invalid, such as being too far in the future, or formatted incorrectly.
  • FIELD_VALUE_TOO_SMALL: The value in the field is lower than the required minimum; for example, a negative price.
  • INCORRECT_JSON_FORMAT: The JSON in the request is incorrectly formatted, such as a missing { bracket.
  • INVALID_LANGUAGE_CODE: The language code is incorrectly formatted.
  • FIELD_VALUE_EXCEEDED: The value in the field is higher than the allowed maximum.
  • INVALID_RESOURCE_ID: The resource ID is invalid; for example, a non-existent catalog_id in the resource name.
  • FIELD_SIZE_EXCEEDED: The number of entries in the field exceeds the maximum limit.
  • UNEXPECTED_FIELD: A field that was expected to be empty has a value; for example, a transaction for a detail page view event.
  • INVALID_FORMAT: The field is not formatted correctly, such as a malformed string
  • RESOURCE_ALREADY_EXISTS: You tried to create a resource that already exists, such as a previously created catalog item.
  • INVALID_API_KEY: The API key does not match the project in your request.
  • INSUFFICIENT_PERMISSIONS: You do not have permission to execute the request; this error is usually related to the lack of a required IAM permission.
  • UNJOINED_WITH_CATALOG: The request includes a catalog item ID that does not exist in the catalog. Make sure your catalog is up to date.
  • BATCH_ERROR: The request has multiple errors; for example, an inline import with 10 items that fail validation for different reasons.
  • INACTIVE_RECOMMENDATION_MODEL: You queried a model that is not active for serving.
  • ABUSIVE_ENTITY: The visitor ID or user ID associated with the request has sent an abnormal number of events in a short period of time.
  • FILTER_TOO_STRICT: The prediction request filter blocked all prediction results. Generic (not personalized) popular items are returned, unless the call specified strictFiltering as false, in which case no items are returned. Some common reasons why this issue occurs:

    • You are specifying a filter tag that doesn't exist in your catalog. It can take up to a day for a filter tag update to take effect.
    • Your filter is too narrow.

Viewing logs directly

You can also open your log files directly in Logging. For example, this link opens logs for all Retail errors in the past hour: Open Retail logs

Viewing data load metrics

After your data upload system is running successfully, you can also use the Catalog and Event tabs on the Retail Data page to view error metrics for your data ingestion to ensure that everything is running smoothly.

You can also add alerts to let you know if something goes wrong with your data upload system.

Catalog data summary

Use the Catalog tab on the Data page to view high-level data statistics for each catalog branch. This page displays how many products you have imported, how many are in stock, and when you last imported products for each product catalog branch.

You can also see a preview of the catalog items you have uploaded, and filter based on product fields.

You can import data to different branches as a way to stage and preview Recommendations AI or Retail Search results. For example, to prepare for a holiday season, you might upload new catalog data to a non- default branch and make sure Retail results are generated correctly before making it live on your website.

User event recording statistics

For each type of user event, you can see in the Event tab how many you have recorded, how many of those were not able to be associated with a product (unjoined events), and how the numbers differed from previous periods. You can select a preset time period or enter custom time range.

The metric graph displays user events ingested over time, which you can filter by user event type.

Data quality metrics

On the Data page, click View data quality to open the Data quality panel.

  • The Catalog tab shows the percentage of products in your catalog that meet each quality metric. The metrics help you evaluate the search quality of your product data.

  • The Event tab shows how many of your user events meet each data quality requirement. The metrics help you evaluate the search quality of your user events. You can filter the results by time range and click View logs for each requirement.

Unjoined events

When a user event or API request refers to a product that has not been uploaded to Retail, it is an unjoined event. Unjoined user events are still logged, and unjoined requests are handled, but neither can be used to further enhance the model for future predictions. For this reason, you should make sure that your unlogged event percentage is very low for both user events and prediction requests.

You can see your unjoined user event percentage in the Event tab on the Data page.

API errors

You can see a graph of API errors over time, displayed by method name, by clicking View API metrics on the button bar of the Monitoring & Analytics page.

Monitor API method activity

For visualizations of traffic, errors, and latency by API method, go to the Monitoring tab on the Monitoring & Analytics page. You can select a preset time period or enter custom time range.

To see more details about each graph:

  • Underneath a graph, click a method name to isolate it in the graph.
  • Hover your cursor over a graph to see a callout with each method and its values at that point in time.
  • Click and drag over any section of the graph to zoom in on that period of time.

What's next