Skip to main content

Rate Limits

The TakeTheme API implements rate limiting to ensure fair usage and maintain service stability. The default limit is 140 requests per 60-second sliding window; some endpoint groups (e.g. analytics) apply their own, stricter per-store limits. Rejected requests do not count against your window, so a retry loop can't extend its own lockout. If you need custom limits, email support@taketheme.com.

Rate Limit Headers​

Rate-limited responses include these headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 140
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 24
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetSeconds until capacity frees up (not a timestamp)

API Key Usage Quotas​

Separate from the per-window rate limit, an API key can be created with a total usage quota. Responses to key-authenticated requests report quota state in the same header family, plus a bucket identifier:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99312
X-RateLimit-Reset: 0
X-RateLimit-Bucket: 665f2a...

Here Limit/Remaining reflect the key's lifetime quota (Reset: 0 means there is no time-based reset), and X-RateLimit-Bucket is the API key's ID. When the quota is exhausted the API returns 429 API_KEY_USAGE_LIMIT_REACHED.

Rate Limit Exceeded​

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

{
  "message": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "status": 429
}

The response includes a Retry-After header indicating how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 140
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45

Handling Rate Limits​

Exponential Backoff​

Implement exponential backoff for automatic retries:

async function fetchWithBackoff(url, options, maxRetries = 5) {
  let delay = 1000; // Start with 1 second

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After");
      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : delay;

      console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
      await new Promise((resolve) => setTimeout(resolve, waitTime));

      delay *= 2; // Double the delay for next attempt
      continue;
    }

    return response;
  }

  throw new Error("Max retries exceeded");
}

Python Implementation​

import time
import requests
from functools import wraps

def retry_with_backoff(max_retries=5, base_delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            delay = base_delay
            for attempt in range(max_retries):
                response = func(*args, **kwargs)

                if response.status_code == 429:
                    retry_after = int(response.headers.get('Retry-After', delay))
                    print(f"Rate limited. Waiting {retry_after}s...")
                    time.sleep(retry_after)
                    delay *= 2
                    continue

                return response

            raise Exception("Max retries exceeded")
        return wrapper
    return decorator

@retry_with_backoff(max_retries=5)
def get_products(api_key):
    return requests.get(
        'https://api.taketheme.com/api/v1/product',
        headers={'tt-api-key': f'{api_key}'}
    )

Proactive Rate Limiting​

Monitor remaining requests and slow down before hitting limits:

class RateLimitedClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.remaining = Infinity;
    this.resetTime = 0;
  }

  async request(endpoint, options = {}) {
    // Wait if we're close to the limit
    if (this.remaining < 5) {
      const waitTime = (this.resetTime - Date.now() / 1000) * 1000;
      if (waitTime > 0) {
        console.log(`Approaching rate limit. Waiting ${waitTime}ms...`);
        await new Promise((resolve) => setTimeout(resolve, waitTime));
      }
    }

    const response = await fetch(`https://api.taketheme.com/api/v1${endpoint}`, {
      ...options,
      headers: {
        "tt-api-key": this.apiKey,
        "Content-Type": "application/json",
        ...options.headers,
      },
    });

    // Update rate limit tracking (Reset is seconds until capacity frees)
    this.remaining = parseInt(
      response.headers.get("X-RateLimit-Remaining") || "0"
    );
    const resetSeconds = parseInt(response.headers.get("X-RateLimit-Reset") || "0");
    this.resetTime = Date.now() / 1000 + resetSeconds;

    return response;
  }
}

Requesting Higher Limits​

If you need higher rate limits:

  1. Upgrade your plan — Higher tiers include increased limits
  2. Contact sales — For enterprise-level requirements, reach out to sales@taketheme.com
  3. Optimize your integration — Often, architectural changes can reduce the need for higher limits