Rate Limits

Rate limiting ensures fair usage and API stability for all users.

Limits by Tier

Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

Example:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1709568060

Handling 429 Responses

When rate limited, the API returns HTTP 429 Too Many Requests:

{
  "detail": "Rate limit exceeded. Retry after 60 seconds."
}

Recommended Retry Strategy

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")

Best Practices

1. Implement exponential backoff - Don't hammer the API when rate limited
2. Cache responses - Cache frequently accessed data to reduce API calls
3. Use webhooks - For high-volume scenarios, consider webhook subscriptions
4. Monitor headers - Track X-RateLimit-Remaining to stay within limits

Ingestion Limits

The ingestion endpoints (/v1/ingest/*) have separate limits:

• 100 requests/minute per API key
• 1000 products per batch

This is to ensure scraping pipelines don't impact search performance.