Rate Limits

Understand and manage your API usage limits to ensure optimal performance.

Overview

Rate limits help ensure fair usage of the API and maintain service quality for all users.

Rate Limit Tiers

Environment	Requests per Minute	Requests per Hour	Requests per Day
Sandbox	100	1,000	10,000
Production	1,000	10,000	100,000

Rate Limit Headers

All API responses include rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642234567
X-RateLimit-Reset-Time: 2024-01-15T11:30:00Z

Header Descriptions

X-RateLimit-Limit: Maximum requests allowed in the current window
X-RateLimit-Remaining: Number of requests remaining in the current window
X-RateLimit-Reset: Unix timestamp when the rate limit resets
X-RateLimit-Reset-Time: Human-readable time when the rate limit resets

Rate Limit Windows

Per Minute: Resets every minute
Per Hour: Resets every hour
Per Day: Resets at midnight UTC

Rate Limit Errors

When you exceed your rate limit, you'll receive a 429 status code:

{
  "status": false,
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "data": [],
  "errors": ["Too many requests"],
  "response_code": "429"
}

Best Practices

1. Monitor Your Usage

// Check rate limit headers
const response = await fetch('/api/endpoint');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Remaining requests: ${remaining}`);
console.log(`Reset time: ${new Date(reset * 1000)}`);

2. Implement Exponential Backoff

async function makeRequestWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      const data = await response.json();
      
      if (data.response_code === "429") {
        const retryAfter = 60; // Default 60 seconds
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      return data;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

3. Cache Responses

const cache = new Map();

async function cachedRequest(url) {
  if (cache.has(url)) {
    const { data, timestamp } = cache.get(url);
    if (Date.now() - timestamp < 5 * 60 * 1000) { // 5 minutes
      return data;
    }
  }
  
  const response = await fetch(url);
  const data = await response.json();
  
  cache.set(url, { data, timestamp: Date.now() });
  return data;
}

Code Examples

JavaScript Rate Limit Monitoring

async function makeApiRequest(url, options = {}) {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers
    },
    ...options
  });

  // Check rate limit headers
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
  
  if (remaining !== null && limit !== null) {
    const usagePercentage = ((limit - remaining) / limit) * 100;
    
    if (usagePercentage > 80) {
      console.warn(`High rate limit usage: ${usagePercentage.toFixed(1)}%`);
    }
  }

  const data = await response.json();
  
  if (!data.status) {
    throw new Error(`API Error: ${data.message}`);
  }
  
  return data;
}

Python Rate Limit Handling

import requests
import time

def make_api_request(url, headers=None, data=None):
    try:
        response = requests.post(
            url,
            headers=headers,
            json=data
        )
        
        # Check rate limit headers
        remaining = response.headers.get('X-RateLimit-Remaining')
        limit = response.headers.get('X-RateLimit-Limit')
        
        if remaining and limit:
            usage_percentage = ((int(limit) - int(remaining)) / int(limit)) * 100
            if usage_percentage > 80:
                print(f"Warning: High rate limit usage: {usage_percentage:.1f}%")
        
        result = response.json()
        
        if not result.get('status'):
            if result.get('response_code') == '429':
                print("Rate limit exceeded, waiting 60 seconds...")
                time.sleep(60)
                return make_api_request(url, headers, data)
            else:
                raise Exception(f"API Error: {result.get('message')}")
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        raise

PHP Rate Limit Management

function makeApiRequest($url, $headers = [], $data = null) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    if ($data) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    // Parse headers and body
    $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $headers = substr($response, 0, $headerSize);
    $body = substr($response, $headerSize);
    
    // Check rate limit headers
    if (preg_match('/X-RateLimit-Remaining: (\d+)/', $headers, $matches)) {
        $remaining = intval($matches[1]);
    }
    if (preg_match('/X-RateLimit-Limit: (\d+)/', $headers, $matches)) {
        $limit = intval($matches[1]);
    }
    
    if (isset($remaining) && isset($limit)) {
        $usagePercentage = (($limit - $remaining) / $limit) * 100;
        if ($usagePercentage > 80) {
            error_log("Warning: High rate limit usage: " . round($usagePercentage, 1) . "%");
        }
    }
    
    $result = json_decode($body, true);
    
    if (!$result['status']) {
        if ($result['response_code'] === '429') {
            error_log("Rate limit exceeded, waiting 60 seconds...");
            sleep(60);
            return makeApiRequest($url, $headers, $data);
        } else {
            throw new Exception("API Error: " . $result['message']);
        }
    }
    
    return $result;
}

Upgrading Your Plan

If you need higher rate limits:

Contact Support: Reach out to our support team
Review Usage: Analyze your current API usage patterns
Optimize Requests: Implement caching and request batching
Plan Upgrade: Choose the appropriate plan for your needs

Monitoring and Alerts

Set up monitoring for your rate limit usage:

// Monitor rate limit usage
function checkRateLimit(response) {
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
  
  if (remaining !== null && limit !== null) {
    const usagePercentage = ((limit - remaining) / limit) * 100;
    
    if (usagePercentage > 80) {
      console.warn(`High rate limit usage: ${usagePercentage.toFixed(1)}%`);
      // Send alert to your monitoring system
    }
  }
}

Rate Limits

On this page