Rate Limiting

The Business API enforces per-merchant rate limits to ensure fair usage and platform stability.

Response Headers

Every response includes rate limit headers that tell you your current quota:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Check these headers on every response to know your limit and how many requests you have left.

Handling 429 Too Many Requests

When you exceed the limit, the API responds with status 429 and adds a Retry-After header:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710288000

{
  "type": "RateLimitExceededError",
  "detail": "Rate limit exceeded"
}

Retry Strategy

Use exponential backoff when you receive a 429 response:

import time
import httpx

def request_with_retry(url: str, headers: dict, max_retries: int = 3):
    for attempt in range(max_retries):
        response = httpx.get(url, headers=headers)
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)
    return response

async function requestWithRetry(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { headers });
    if (response.status !== 429) return response;
    const retryAfter = parseInt(response.headers.get("Retry-After") || 2 ** attempt);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
}

Best Practices

Monitor the X-RateLimit-Remaining header to proactively slow down before hitting the limit.
Cache responses when the data doesn’t change frequently — especially product catalogs.
Batch your work — fetch larger pages (up to limit=100) to reduce the number of requests.
Respect Retry-After — always wait the indicated time before retrying, rather than using a fixed delay.