Rate limits

The ListBee API enforces rate limits to ensure fair usage and platform stability. Limits are applied per API key and vary by endpoint type.

Limits by endpoint

Rate limit headers

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

# Example response headers
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1742486460

Exceeding the limit

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Retry-After: 32

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 32 seconds."
  }
}

The Retry-After header tells you how many seconds to wait before making another request.

Handling rate limits

Python

import time
import httpx

def api_request(method, url, **kwargs):
    for attempt in range(3):
        resp = httpx.request(method, url, **kwargs)
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue
        return resp
    raise Exception("Rate limit exceeded after 3 retries")

Node.js

async function apiRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const resp = await fetch(url, options);
    if (resp.status === 429) {
      const retryAfter = parseInt(resp.headers.get("Retry-After") || "60");
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    return resp;
  }
  throw new Error("Rate limit exceeded after retries");
}

Best practices

• Respect Retry-After. Always wait the indicated time before retrying a 429 response.
• Use exponential backoff. If the Retry-After header is missing, use exponential backoff starting at 1 second.
• Cache read results. Reduce read requests by caching listing and order data locally.
• Use webhooks. Instead of polling the orders endpoint, set up webhooks for real-time order notifications.
• Batch operations. Create listings in sequence with a small delay rather than firing all requests simultaneously.

Higher limits

If you need higher rate limits for your use case, contact us to discuss Enterprise plans with custom limits.