Recommendation Response Details

The following table demonstrates the status codes and response types from the Recommendation API. The table lists Status Codes, their descriptions, and scenarios that you can receive these status codes.

200 / Success-OK

Successful Recommendation API requests receive an API endpoint that contains the following fields:

• success field that denotes the success of the API response,

• total field displays the number of recommendations returned from the API response,

• types field that lists recommendation algorithm types that returned from the endpoint,

• data field lists the recommendations and their details

Following is a successful Recommendation API request and its example response:

Sample Request

https://recommendationv2.api.useinsider.com/v2/most-popular?details=true&partnerName=yourPartnerName&locale=en_US&currency=USD&size=1

Sample Response

{
    "success": true,
    "total": 1,
    "types": {
        "mvop": 1
    },
    "data": [
        {
            "image_url": "http://insiderone.com/img/p/1/3/13.jpg",
            "name": "Hummingbird cushion",
            "item_id": "11",
            "url": "https://insiderone.com/home-accessories/11-hummingbird-cushion.html#ins_sr=eyJwcm9kdWN0SWQiOiIxMSJ9",
            "description": "Hummingbird cushion in category Home Accessories",
            "in_stock": 1,
            "price": {
                "USD": 0.57
            },
            "locale": "en_US",
            "product_attributes": {
                "test": "productTest",
                "testattributes": "productTest"
            },
            "category": [
                "Home Accessories"
            ],
            "discount": {
                "USD": 0.0
            },
            "original_price": {
                "USD": 0.57
            }
        }
    ]
}

400 / Bad Request

In the following scenarios, the Recommendation API returns responses with a 400 status code:

• Missing required endpoint parameters

• Missing required endpoint parameter values

• Wrong usage of endpoint parameters

Following API requests and responses demonstrate examples of these scenarios.

Sample Request 1

The partnerName parameter is missing in the request below:

https://recommendationv2.api.useinsider.com/v2/most-popular?details=true&currency=USD&locale=en_US

Sample Response 1

{
    "success": false,
    "message": "Missing parameter: partnerName",
    "data": []
}

Sample Request 2

The locale value is missing in the request below:

https://recommendationv2.api.useinsider.com/v2/most-popular?details=true&currency=USD&locale=&partnerName=yourPartnerName

Sample Response 2

{
    "success": false,
    "message": "Locale is invalid.",
    "data": []
}

403 / Forbidden

The Recommendation API performs sender origin validation for partners that enable the Origin/CORS Validation feature. When the feature is enabled, the Recommendation API only provides successful recommendation content to callers from the allowed domains. Requests from domains that are not listed as allowed domains will receive failures with a 403 status code.

Following is the Recommendation API response for unsuccessful validations:

{
    "success": false,
    "message": "Origin validation error.",
    "data": []
}

422 / Unprocessible Content

This endpoint response status code is often received when the partner page that hosts the recommendation campaign cannot provide the details that the Recommendation API endpoint needs to use.

As an example scenario;

• You create and activate a Web Smart Recommender campaign on Product Pages that has Dynamic Filtering usage on the color field.

• In Dynamic Filtering, the attribute values of fields used in filters are fetched from the Recommendation API.

• Thus, web clients are not informed whether the requested attribute is present for the current product.

• In cases where the attribute value that is used in the Dynamic Filter is missing, the Recommendation API cannot perform the Dynamic Filter.

• The API returns with a 422 status code for those cases.

Sample Request

https://recommendationv2.api.useinsider.com/v2/most-popular?details=true&filter=([color][=][${value}])&currency=TRY&locale=tr_TR&partnerName=yourPartnerName&productId=11

Sample Response

The color attribute was missing for the given item with ID “11”. When this attribute is requested with dynamic filtering, the Recommendation API responds with a 422 status code (denoting that an unprocessible content is present)

{
    "success": false,
    "message": "The field 'color' in dynamic filter was not found in the product.",
    "data": []
}

429 / Too Many Requests

When you exceed the rate limit, the Recommendation API will temporarily throttle your requests. Rate limits are calculated using a rolling one-minute window, so if you're throttled, you'll regain access once the current window resets (at most one minute).

{
    "success": false,
    "message": "Rate exceeded.",
    "data": []
}