Rate Limits Guide

Overview

SmartLead applies rate limits to protect the platform and ensure fair access for all users. This guide explains the rate limit structure, how to detect when you’re being throttled, and strategies for building efficient integrations.

Rate Limit Structure

SmartLead enforces rate limits on a per-API-key basis:

Tier	Requests per Minute	Requests per Hour	Burst Limit
Standard	60	1,000	10 requests/second
Pro	120	3,000	20 requests/second
Enterprise	Custom	Custom	Custom

This plan-wide limit applies to your API key across all endpoints combined. A mix of campaign, lead, and analytics requests all count toward the same limit.

Endpoint-Specific Rate Limits

A small number of endpoints are expensive enough to serve that they carry their own dedicated rate limit, independent of the plan-wide limit above.

Endpoint	Limit	Window	Scope
`GET /campaigns/{campaign_id}/leads-statistics`	10 requests	60 seconds	Per account, across all campaigns
`GET /campaigns/all-leads-activities`	10 requests	60 seconds	Per account
`GET /analytics/mailbox/domain-wise-health-metrics`	10 requests	60 seconds	Per account

These limits stack on top of the plan-wide limit rather than replacing it:

Requests to these endpoints still count toward your plan-wide quota.
Having plan-wide quota remaining does not let you exceed the endpoint’s own limit.
Each endpoint has its own counter, so they do not consume each other’s budget.

The window starts on your first request to that endpoint and resets 60 seconds later. Exceeding it returns 429 Too Many Requests with a plain-text body rather than the JSON error shape shown below:

429 - Too Many Requests

You have exceeded the 10 requests in 60 sec limit for this endpoint!

Endpoint-specific 429s do not include Retry-After or X-RateLimit-* headers, so the backoff helpers on this page cannot read a retry delay from them. Fall back to a fixed wait of up to 60 seconds for these endpoints.

If you are polling these endpoints for changes, use their time-filter parameters (event_time_gt on leads-statistics, event_time_from / event_time_to on all-leads-activities, start_date / end_date on domain-wise-health-metrics) to fetch only what changed since your last call, and request the maximum page size so each of your 10 requests does as much work as possible.

Detecting Rate Limits

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

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 30 seconds.",
    "retry_after": 30
  }
}

Rate Limit Headers

Check response headers to monitor your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429)

Python

import requests
import os

API_KEY = os.getenv("SMARTLEAD_API_KEY")
BASE_URL = "https://server.smartlead.ai/api/v1"

response = requests.get(
    f"{BASE_URL}/campaigns/",
    params={"api_key": API_KEY}
)

# Check rate limit status
limit = response.headers.get("X-RateLimit-Limit")
remaining = response.headers.get("X-RateLimit-Remaining")
reset = response.headers.get("X-RateLimit-Reset")

print(f"Limit: {limit} | Remaining: {remaining} | Resets at: {reset}")

Backoff Strategies

Exponential Backoff with Jitter

The recommended approach for handling rate limits:

Python

import time
import random

def request_with_backoff(method, endpoint, payload=None, max_retries=5):
    """Make request with exponential backoff on rate limits."""
    for attempt in range(max_retries + 1):
        response = requests.request(
            method,
            f"{BASE_URL}/{endpoint}",
            params={"api_key": API_KEY},
            json=payload,
            timeout=30
        )

        if response.status_code == 429:
            if attempt == max_retries:
                raise Exception("Rate limit exceeded after max retries")

            # Use Retry-After header if available
            retry_after = response.headers.get("Retry-After")
            if retry_after:
                delay = float(retry_after)
            else:
                # Exponential backoff: 1s, 2s, 4s, 8s, 16s
                delay = (2 ** attempt) + random.uniform(0, 1)

            print(f"Rate limited. Waiting {delay:.1f}s (attempt {attempt + 1})")
            time.sleep(delay)
            continue

        response.raise_for_status()
        return response.json()

Proactive Rate Limiting

Instead of waiting for 429s, track your usage and throttle proactively:

Python

import time
from collections import deque

class RateLimiter:
    """Client-side rate limiter to avoid 429 errors."""

    def __init__(self, max_per_minute=50):
        self.max_per_minute = max_per_minute
        self.requests = deque()

    def wait_if_needed(self):
        """Block until it's safe to make another request."""
        now = time.time()

        # Remove requests older than 60 seconds
        while self.requests and self.requests[0] < now - 60:
            self.requests.popleft()

        if len(self.requests) >= self.max_per_minute:
            # Wait until the oldest request expires
            wait_time = 60 - (now - self.requests[0])
            if wait_time > 0:
                print(f"Throttling: waiting {wait_time:.1f}s")
                time.sleep(wait_time)

        self.requests.append(time.time())

# Usage
limiter = RateLimiter(max_per_minute=50)  # Stay under the 60/min limit

for campaign_id in campaign_ids:
    limiter.wait_if_needed()
    data = make_request("GET", f"campaigns/{campaign_id}/analytics")

Set your client-side limit to 80% of the actual limit (e.g., 50 requests/minute when the limit is 60). This buffer accounts for timing differences and prevents edge-case throttling.

Optimizing Request Patterns

Batch Operations

Instead of making individual requests per lead, use batch endpoints:

Python

# Bad: 100 individual requests
for lead in leads:
    requests.post(f"{BASE_URL}/campaigns/{cid}/leads",
                  params={"api_key": API_KEY},
                  json={"lead_list": [lead]})

# Good: 1 batch request for up to 400 leads
requests.post(f"{BASE_URL}/campaigns/{cid}/leads",
              params={"api_key": API_KEY},
              json={"lead_list": leads[:400]})

Cache Responses

Cache data that doesn’t change often to reduce API calls:

Python

import functools
import time

_cache = {}

def cached_request(endpoint, ttl_seconds=300):
    """Cache GET requests for a specified TTL."""
    now = time.time()

    if endpoint in _cache:
        data, cached_at = _cache[endpoint]
        if now - cached_at < ttl_seconds:
            return data

    data = make_request("GET", endpoint)
    _cache[endpoint] = (data, now)
    return data

# Campaigns list doesn't change often — cache for 5 minutes
campaigns = cached_request("campaigns/", ttl_seconds=300)

# Analytics change frequently — cache for 1 minute
analytics = cached_request(f"campaigns/{cid}/analytics", ttl_seconds=60)

Use Webhooks Instead of Polling

Instead of polling for new replies every few seconds:

Python

# Bad: Polling every 30 seconds (2 requests/minute per campaign)
while True:
    response = requests.get(f"{BASE_URL}/campaigns/{cid}/leads",
                           params={"api_key": API_KEY, "status": "INTERESTED"})
    time.sleep(30)

Set up a webhook to receive events in real time with zero API calls:

Python

# Good: Register a webhook once, receive events instantly
requests.post(f"{BASE_URL}/webhooks",
              params={"api_key": API_KEY},
              json={
                  "webhook_url": "https://yourapp.com/hooks/smartlead",
                  "event_types": ["EMAIL_REPLIED"]
              })

See the Webhook Integration Guide for full details.

Parallelize with Rate Awareness

When you need to make many requests, use controlled concurrency:

Python

import concurrent.futures
import time

limiter = RateLimiter(max_per_minute=50)

def fetch_campaign_data(campaign_id):
    limiter.wait_if_needed()
    return make_request("GET", f"campaigns/{campaign_id}/analytics")

# Process campaigns with controlled parallelism
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    futures = {
        executor.submit(fetch_campaign_data, cid): cid
        for cid in campaign_ids
    }

    for future in concurrent.futures.as_completed(futures):
        cid = futures[future]
        try:
            data = future.result()
            print(f"Campaign {cid}: {data.get('total_sent', 0)} sent")
        except Exception as e:
            print(f"Campaign {cid} failed: {e}")

Troubleshooting

Getting 429 errors with low request volume

Check if another integration or script is using the same API key. Rate limits are per-key, not per-client. Consider using separate API keys for different integrations.

Rate limits feel too restrictive

Review your request patterns — are you polling when you could use webhooks? Are you making individual requests when batch endpoints are available? If you genuinely need higher limits, contact SmartLead support about Enterprise plans.

Retry-After header is missing on 429 response

Default to exponential backoff starting at 1 second. Most rate limit windows reset within 60 seconds.

Get Started

Core Concepts

Guides

Overview

Rate Limit Structure

Endpoint-Specific Rate Limits

Detecting Rate Limits

Rate Limit Headers

Backoff Strategies

Exponential Backoff with Jitter

Proactive Rate Limiting

Optimizing Request Patterns

Batch Operations

Cache Responses

Use Webhooks Instead of Polling

Parallelize with Rate Awareness

Troubleshooting

What’s Next?

Error Handling Guide

Best Practices

​Overview

​Rate Limit Structure

​Endpoint-Specific Rate Limits

​Detecting Rate Limits

​Rate Limit Headers

​Backoff Strategies

​Exponential Backoff with Jitter

​Proactive Rate Limiting

​Optimizing Request Patterns

​Batch Operations

​Cache Responses

​Use Webhooks Instead of Polling

​Parallelize with Rate Awareness

​Troubleshooting

​What’s Next?

Error Handling Guide

Best Practices

Overview

Rate Limit Structure

Endpoint-Specific Rate Limits

Detecting Rate Limits

Rate Limit Headers

Backoff Strategies

Exponential Backoff with Jitter

Proactive Rate Limiting

Optimizing Request Patterns

Batch Operations

Cache Responses

Use Webhooks Instead of Polling

Parallelize with Rate Awareness

Troubleshooting

What’s Next?