> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt > Use this file to discover all available pages before exploring further. # Recommendation Requests > Learn how to get item recommendations from the Recommendation API, show them, and prepare for empty results and failed requests. The Recommendation API returns a list of items using the recommendation policy set on an ad unit. This page covers how to request recommendations, show the returned items, and prepare for empty results and failed requests. ## Before you begin * **API URL:** Check your [API URL](https://docs.aiderx.io/development/en/api-access-and-auth.md). Recommendation requests do not require an access token. * **Ad unit:** Get the ID of an ad unit with recommendations enabled from your A2 contact. Your A2 contact sets the recommendation policy, the number of items, and the impression tracking mode on the ad unit. * **Catalog:** Register the items to recommend in [Product Catalog](https://docs.aiderx.io/development/en/catalog.md). `catalog_id` in the response is the item ID in the catalog. ## Build the request When you need a recommendation list, call `POST /app/v0/recommendation/{tagid}` from the client (web or app) or your server. Put the ad unit ID in `tagid`. See [Serving Recommendation](https://docs.aiderx.io/en/0.5.0/decision/recommendation-serving/serving-recommendation.md) in the API Reference for the available fields. ```bash theme={null} curl -i -X POST "/app/v0/recommendation/" \ -H "Content-Type: application/json" \ -d '{"user": {"id": "user-123"}}' ``` | Field | When to use | | - | - | | `user.id` | The user identifier. Always send the same value for the same user. Without it, the user cannot be assigned to a recommendation experiment, and user-history conditions in the recommendation policy (such as excluding items already seen) do not apply. | | `seed_item_id` | The catalog ID of a reference item. Use it with policies that recommend based on a specific item, such as related items on a product detail page. | | `filter` | Conditions for excluding items from recommendations. The available conditions depend on the catalog, so check with your A2 contact. Each array can hold up to 100 values. | The number of items is set on the ad unit, not in the request. | Caller | What to do after receiving the response | | - | - | | Client | Show the list with the response items, and send recommendation events with `tracking_token` and each item's `position`. | | Server | Pass the response to the client. Pass each item's `catalog_id` and `position`, and each list's `tracking_token`. Even if your rules remove some items or change the order, keep the original response `position`, not the on-screen order. | ## Handle the response ```json Recommendation response example theme={null} { "version": "0.1.0", "items": [ { "catalog_id": "catalog-123", "position": 0, "score": 0.87 }, { "catalog_id": "catalog-234", "position": 1 } ], "tracking_token": "", "ext": { "ad_log_tracking_mode": "on_event_tracker" } } ``` | Field | Description | | - | - | | `items[].catalog_id` | The catalog ID of the recommended item. Look up display information such as the name and image in your service's product data. | | `items[].position` | The zero-based recommendation order. Put it as is in `event_position` of recommendation events. | | `items[].score` | The recommendation score. It may be absent depending on the recommendation method. | | `tracking_token` | The tracking token of this recommendation result. Put it as is in recommendation events. | | `ext.ad_log_tracking_mode` | The impression tracking mode. See [Recommendation Event Tracking](https://docs.aiderx.io/development/en/reco-events-and-logs.md#response-impression-tracking). | Handle the response as follows. | Response | Handling | | - | - | | HTTP `200` with `items` | Show the items and keep `tracking_token`. | | HTTP `200` with empty `items` | Hide the recommendation area or show your service's default list. There are no recommendation events to send. | | Error status or network failure | Show your service's default list. The response has no `tracking_token`. | ### Failed requests Set a maximum time your service waits for recommendations. If that time passes or the request fails, replace it with your service's default list, and do not show responses that arrive later. With the default settings, A2 returns HTTP `408` for requests it cannot process within one second. Error responses include `errorcode` and `ext.message`. | HTTP status | `errorcode` | Cause | What to check | | - | - | - | - | | `408` | None | A2 could not process the recommendation within one second with the default settings. | Replace it with your service's default list. If it repeats, send the time and ad unit ID to your A2 contact. | | `400` | `1300` | `tagid` is not a UUID. | Check the ad unit ID in the request path. | | `400` | `1304` | An array in `filter` has more than 100 values. | Reduce the number of exclusion values. | | `404` | `1301` | The ad unit was not found. | Check that the ad unit ID and the A2 environment match. | | `422` | `1302` | Recommendations are not enabled on the ad unit. | Ask your A2 contact to set up recommendations. | | `422` | `1303` | The ad unit has no recommendation policy to apply. | Ask your A2 contact to check the recommendation policy. | ```json Error response example theme={null} { "version": "0.1.0", "errorcode": "1302", "items": [], "ext": { "message": "Recommendation not enabled." } } ``` If you request again, the recommendation result and `tracking_token` may change. Use the values of the response you actually showed in events. With On Recommendation Response (`on_ad_response`), responses that were not shown are also counted as responses. ## Next steps See [Recommendation Event Tracking](https://docs.aiderx.io/development/en/reco-events-and-logs.md) to send impressions, clicks, and conversions of the recommendations you show. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.