Rate Limiting

Overview

Rate limits protect the API from abuse and ensure stable performance for all users. Each API key has specific limits based on your plan.

Why Rate Limits?

• Stability: Prevents API server overload
• Fair use: Ensures equal access for all users
• Cost control: Protects against unintentionally high costs
• Error protection: Catches runaway processes or bugs

Rate Limit Tiers

Different plans have different rate limits:

Rate Limit Headers

Each API response includes headers showing your current rate limit status:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Remaining requests in this window
• X-RateLimit-Reset - Unix timestamp when limit resets

Example Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704297600

Calculate time until reset

// PHP
$reset = $headers['X-RateLimit-Reset'];
$secondsUntilReset = $reset - time();
echo "Rate limit resets in {$secondsUntilReset} seconds";

// JavaScript
const reset = parseInt(headers['x-ratelimit-reset']);
const secondsUntilReset = reset - Math.floor(Date.now() / 1000);
console.log(`Rate limit resets in ${secondsUntilReset} seconds`);

Handling 429 Too Many Requests

When you exceed the rate limit, you'll receive a 429 response:

429 Response Format

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

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Retry-After Header

429 responses include a Retry-After header telling you how many seconds to wait before trying again.

Retry Strategies

Best Practices

Follow these best practices to stay within rate limits:

Code Examples

Examples of handling rate limiting in different languages:

PHP with Retry Logic

function makeApiRequest($url, $apiKey, $maxRetries = 3) {
    $attempt = 0;

    while ($attempt < $maxRetries) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}"],
            CURLOPT_HEADER => true,
        ]);

        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $headers = substr($response, 0, $headerSize);
        $body = substr($response, $headerSize);

        curl_close($ch);

        if ($statusCode === 429) {
            // Extract Retry-After header
            preg_match('/Retry-After:\s*(\d+)/i', $headers, $matches);
            $retryAfter = $matches[1] ?? pow(2, $attempt);

            error_log("Rate limited. Retrying after {$retryAfter}s");
            sleep($retryAfter);
            $attempt++;
            continue;
        }

        return json_decode($body, true);
    }

    throw new Exception('Max retries exceeded');
}

Node.js with Exponential Backoff

async function makeApiRequest(url, apiKey, maxRetries = 3) {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch(url, {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      });

      if (response.status === 429) {
        const retryAfter = parseInt(
          response.headers.get('retry-after') || Math.pow(2, attempt)
        );

        console.log(`Rate limited. Retrying after ${retryAfter}s`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        attempt++;
        continue;
      }

      return await response.json();
    } catch (error) {
      console.error('Request failed:', error);
      attempt++;
    }
  }

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

Python with Rate Limit Tracking

import requests
import time

def make_api_request(url, api_key, max_retries=3):
    attempt = 0
    headers = {'Authorization': f'Bearer {api_key}'}

    while attempt < max_retries:
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(
                response.headers.get('retry-after', 2 ** attempt)
            )

            print(f'Rate limited. Retrying after {retry_after}s')
            time.sleep(retry_after)
            attempt += 1
            continue

        response.raise_for_status()
        return response.json()

    raise Exception('Max retries exceeded')

Monitoring API Usage

Keep track of your API usage:

Troubleshooting

Common rate limit issues and solutions:

Next Steps

Explore related topics: