Rate Limits

Rate Limit Overview

Rate limits protect the API from abuse and ensure fair usage for all customers. Limits are applied per API key.

Plan Limits

Plan	Requests/Minute	Requests/Day	Credits/Month
Free Trial	60	500	2,500 (one-time)
Starter	90	1,000	5,000
Professional	150	5,000	25,000
Business	240	10,000	125,000
Enterprise	360	15,000	600,000

Need custom limits? Contact us for custom enterprise solutions.

Rate Limit Headers

Every authenticated response includes rate limit information in the headers:

X-RateLimit-Limit: 150
X-RateLimit-Remaining: 145
X-RateLimit-Reset: 1786011345
X-RateLimit-Limit-Minute: 150
X-RateLimit-Remaining-Minute: 145
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 4820

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current minute
`X-RateLimit-Reset`	Unix timestamp when the per-minute window resets
`X-RateLimit-Limit-Minute` / `-Remaining-Minute`	Same as the two above, explicitly scoped
`X-RateLimit-Limit-Day` / `-Remaining-Day`	The daily budget and what is left of it

There are two independent budgets. X-RateLimit-Remaining only covers the minute — check X-RateLimit-Remaining-Day too if you run long batches.

Handling Rate Limits

When you exceed either limit, you’ll receive a 429 Too Many Requests with a Retry-After header:

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "retry_after": 45,
  "limits": {
    "per_minute": 150,
    "per_day": 5000,
    "current_minute": 150,
    "current_day": 3204
  },
  "reset_time": {
    "next_minute": "2026-02-10T14:23:00.000000Z",
    "next_day": "2026-02-11T00:00:00.000000Z"
  }
}

retry_after counts seconds to the next window that will actually admit you — the top of the minute normally, midnight if it was the daily budget you exhausted.

A 429 can also mean concurrent_limit_reached: too many enrichments in flight at once (2 on trial, up to 100 on enterprise). Check the error field — waiting a minute will not help there, you need an in-flight enrichment to finish.

Implementation Examples

JavaScript
Python
PHP

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

// Usage
const response = await fetchWithRetry(
  'https://api.bouncewatch.com/api/v1/company/stripe.com',
  { headers: { 'X-API-Key': API_KEY } }
);

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for i in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 2 ** i))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception('Max retries exceeded')

# Usage
response = fetch_with_retry(
    'https://api.bouncewatch.com/api/v1/company/stripe.com',
    headers={'X-API-Key': API_KEY}
)

function fetchWithRetry($url, $headers, $maxRetries = 3) {
    for ($i = 0; $i < $maxRetries; $i++) {
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_HEADER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 429) {
            $retryAfter = pow(2, $i);
            echo "Rate limited. Retrying in {$retryAfter}s...\n";
            sleep($retryAfter);
            continue;
        }
        
        return $response;
    }
    
    throw new Exception('Max retries exceeded');
}

Best Practices

Implement Exponential Backoff

When rate limited, wait progressively longer between retries (1s, 2s, 4s, 8s…)

Queue Your Requests

For bulk operations, implement a request queue to spread requests evenly and stay within limits

Cache Responses

Cache company data for 24 hours to reduce the number of API calls needed

Monitor Your Usage

Check your usage regularly via the dashboard or /account/usage endpoint

For high-volume use cases, consider implementing a simple queue system in your application to automatically space out requests and avoid hitting rate limits.

Configure Webhooks

Set up webhooks to get notified about credit usage →

Getting Started

Core Concepts

AI Agents (MCP)

API Reference

API Playground

Rate Limit Overview

Plan Limits

Rate Limit Headers

Handling Rate Limits

Implementation Examples

Best Practices

Implement Exponential Backoff

Queue Your Requests

Cache Responses

Monitor Your Usage

Configure Webhooks

​Rate Limit Overview

​Plan Limits

​Rate Limit Headers

​Handling Rate Limits

​Implementation Examples

​Best Practices

Implement Exponential Backoff

Queue Your Requests

Cache Responses

Monitor Your Usage

Configure Webhooks

Rate Limit Overview

Plan Limits

Rate Limit Headers

Handling Rate Limits

Implementation Examples

Best Practices