Skip to main content

​
Overview

Our API implements rate limiting to ensure fair usage and maintain service stability for all users. Rate limits are measured in queries (not HTTP requests — see How Queries Are Counted below). When you exceed the rate limit, you’ll receive a 429 Too Many Requests response with helpful headers to guide your retry strategy.

​
Rate Limits

  • Default Rate Limit: 200 queries per minute per API key
  • Rate Limit Window: 60-second sliding window

​
How Queries Are Counted

Rate limits are counted in queries, not in HTTP requests. The number of queries a single API call consumes depends on the endpoint type:
  • Single-entity endpoints: one request equals one query.
  • Bulk / batch endpoints (such as the enrichment and match endpoints): each row (entity) in the request payload counts as a separate query. A single HTTP request that submits 50 entities consumes 50 queries against your limit — not 1.
A single API call is not always a single query. When you send a batch of 50 entities to a bulk endpoint, that one request counts as 50 queries toward your per-minute limit.

​
Examples

API callEndpoint typeEntities in payloadQueries counted
Enrich a batch of 50 businessesBulk5050
Match a batch of 10 prospectsBulk1010
Enrich a single businessSingle11
Because each entity is a query, the X-RateLimit-Remaining header decrements by the number of entities in your request — not by 1 per call. Size your batches accordingly to stay within the 200-queries-per-minute limit.

​
Rate Limit Headers

When making requests to our API, the following headers are included in every response to help you track your usage:
HeaderDescriptionExample
X-RateLimit-LimitMaximum number of queries allowed in the current window200
X-RateLimit-RemainingNumber of queries remaining in the current window150
X-RateLimit-ResetUnix timestamp when the rate limit window resets1234567890
Retry-AfterNumber of seconds to wait before retrying (only included in 429 responses)60

​
Rate Limit Response

When you exceed the rate limit, you’ll receive the following response:
HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1234567890
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "API rate limit exceeded. Please retry after 60 seconds.",
  "retry_after": 60
}

​
Implementing Retry Logic

​
Best Practices

  1. Always check for 429 responses and implement exponential backoff
  2. Respect the Retry-After header - this tells you the minimum time to wait
  3. Monitor your usage using the X-RateLimit-Remaining header
  4. Account for batch size - remember each entity in a bulk request counts as a query
  5. Implement preemptive throttling when X-RateLimit-Remaining is low

​
Example Implementation

import time
import requests
from typing import Dict, Any, Optional

class APIClient:
    def __init__(self, api_key: str, base_url: str):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}'
        })

    def make_request(
        self,
        endpoint: str,
        method: str = 'GET',
        max_retries: int = 3,
        **kwargs
    ) -> Dict[str, Any]:
        """Make an API request with automatic retry logic."""
        url = f"{self.base_url}{endpoint}"
        retry_count = 0

        while retry_count < max_retries:
            try:
                response = self.session.request(method, url, **kwargs)

                # Log rate limit information
                remaining = response.headers.get('X-RateLimit-Remaining')
                if remaining:
                    print(f"Rate Limit Remaining: {remaining}")

                response.raise_for_status()
                return response.json()

            except requests.exceptions.HTTPError as e:
                if e.response.status_code == 429:
                    retry_count += 1

                    # Get retry delay from header
                    retry_after = e.response.headers.get('Retry-After')
                    if retry_after:
                        delay = int(retry_after)
                    else:
                        # Exponential backoff with jitter
                        delay = min(2 ** retry_count, 60)

                    print(f"Rate limit hit. Retrying after {delay} seconds...")

                    if retry_count < max_retries:
                        time.sleep(delay)
                        continue

                raise

        raise Exception("Max retries exceeded")

# Usage example
client = APIClient('your-api-key', 'https://api.example.com')

try:
    data = client.make_request('/users', method='GET')
    print('Data:', data)
except Exception as e:
    print(f'Error: {e}')

​
Monitoring Rate Limits

​
Preemptive Rate Limiting

To avoid hitting rate limits, monitor the X-RateLimit-Remaining header and implement throttling. Remember that X-RateLimit-Remaining reflects queries remaining, so a single bulk request can consume many at once:
JavaScript
// JavaScript example
if (response.headers['x-ratelimit-remaining'] < 10) {
  // Slow down requests when approaching limit
  await sleep(1000); // Wait 1 second between requests
}

​
Frequently Asked Questions

Repeated rate limit violations may result in temporary suspension of API access. Implement proper retry logic and consider upgrading your plan if you need higher limits.
We use a sliding window approach that tracks queries over the past 60 seconds. Each query timestamp is recorded, and queries older than 60 seconds are removed from the count.
The rate limit counts queries, not HTTP requests. For bulk and batch endpoints (such as enrichment and match), every row (entity) in your request payload counts as one query. For example, a single request that submits 50 entities to a batch endpoint consumes 50 queries from your per-minute limit — not 1. Single-entity endpoints count as one query per request.
Rate limits are applied per API key. Each API key has its own independent rate limit counter.
Currently, all endpoints share the same rate limit of 200 queries per minute. Keep in mind that bulk and batch endpoints count each entity in the payload as a separate query, so a single call to those endpoints can consume multiple queries. Some endpoints may have additional specific limits which will be documented separately.