Browse API: Overview

The Browse API is a robust tool designed to enhance the interactivity and customizability of merchandised category pages. It allows for detailed queries that retrieve product information, facets, and sort orders. Additionally, you can apply various filters and create custom sort orders to tailor the browsing experience to your users’ needs.

​

Features and Operations

• Product Retrieval: Fetch detailed product information to display on your category pages.
• Dynamic Filtering: Apply real-time filters based on user selections or predefined criteria.
• Sorting: Implement custom sort logic to highlight featured products or adhere to user preferences.
• Faceted Search: Allow users to narrow down their search based on multiple attributes simultaneously.

​

Rate Limiting

While there is no strict rate limit on the Browse API, we employ intelligent DDoS protection that scales with the nature of the traffic:

• Trusted Environments: Higher limits for serverless environments like AWS Lambda@Edge.
• Malicious Traffic: Immediate blocks for known malicious bots, while trusted bots like GoogleBot are exempt for SEO purposes.
• Impact on Service: We monitor traffic to ensure service availability and may adjust limits as necessary.

​

Error Handling

The Browse API utilizes an industry-standard validation error schema, making it easy to identify and resolve issues within your queries. The API will typically return an HTTP 422 (Unprocessable Entity) status code for validation errors, accompanied by a detailed JSON payload that outlines the nature of the problem.

​

Error Response Format

An error response from the Browse API will include a message field describing the error in human-readable terms and an errors object that lists specific issues for each field. This structure is useful for identifying invalid parameters, missing required fields, or unsupported filter/sort combinations.

Example of a typical validation error response:

{
    "message": "The selected sort order code is invalid.",
    "errors": {
        "sort_order_code": [
            "The selected sort order code is invalid."
        ]
    }
}

​

Common Error Scenarios

​

Missing Required Parameters

When a required parameter is missing from the request, the API will return a message indicating the field that is absent:

{
    "message": "The given data was invalid.",
    "errors": {
        "sort_order_code": [
            "The sort order code field is required."
        ]
    }
}

​

Handling Empty Collections

The Browse API will never return an error for an empty result set. Instead, the response will include an empty products array, allowing for smooth rendering of empty states in your UI without additional error handling.

Example of an empty collection response:

{
    "totalResults": 0,
    "results": [],
    "totalPages": 0
}