API and developers

Rate Limiting

Understand request limits and how to handle 429 responses

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

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.
Need help?