Rate Limits

Rate limits protect the API from abuse and ensure fair usage across all users.

Limits by plan

| Plan | Requests/month | Burst rate (req/min) | |---|---|---| | Free | 100 | 10 | | Starter | 5,000 | 30 | | Growth | 25,000 | 60 | | Scale | 100,000 | 120 |

Rate limit headers

Every API response includes rate limit information:

| Header | Description | |---|---| | X-RateLimit-Limit | Maximum requests per minute for your plan | | X-RateLimit-Remaining | Requests remaining in the current window | | X-RateLimit-Reset | Unix timestamp when the window resets |

When you hit the limit

You'll receive a 429 Too Many Requests response:

{
  "success": false,
  "request_id": "req_abc123",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait before making more requests."
  }
}

Handling rate limits

JavaScript

async function classifyWithRetry(email, apiKey, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(
      `https://emailkind.com/v1/classify?email=${encodeURIComponent(email)}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    if (res.status !== 429) return res.json();

    const wait = Math.pow(2, attempt) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error("Rate limit exceeded after retries");
}

Python

import time
import requests

def classify_with_retry(email, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(
            "https://emailkind.com/v1/classify",
            params={"email": email},
            headers={"Authorization": f"Bearer {api_key}"}
        )
        if response.status_code != 429:
            return response.json()

        wait = 2 ** attempt
        time.sleep(wait)

    raise Exception("Rate limit exceeded after retries")

PHP

function classifyWithRetry(string $email, string $apiKey, int $maxRetries = 3): array {
    for ($attempt = 0; $attempt < $maxRetries; $attempt++) {
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => "https://emailkind.com/v1/classify?" . http_build_query(["email" => $email]),
            CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"],
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($status !== 429) {
            return json_decode($body, true);
        }

        sleep(pow(2, $attempt));
    }
    throw new \Exception("Rate limit exceeded after retries");
}

Check headers proactively

const response = await fetch(url, { headers });
const remaining = response.headers.get("X-RateLimit-Remaining");

if (parseInt(remaining) < 5) {
  // Slow down requests
  await new Promise((r) => setTimeout(r, 1000));
}

Monthly quota

When your monthly quota is reached, all requests return 429 until the next billing cycle. You can:

1. Upgrade your plan for more requests
2. Wait until the next month for the quota to reset
3. Monitor usage in your Dashboard to avoid surprises