Rate Limits

Rate Limits & Usage

Understand SearchHive's rate limiting system, credit usage, and how to handle limits gracefully in your applications.

Rate Limiting Overview

SearchHive uses a combination of rate limiting (requests per minute) and credit-based billing to ensure fair usage and optimal performance for all users.

Rate Limit Tiers

Free

10/minute

1,000/month

5,000 credits

Basic rate limits

Email support

Standard endpoints

Pro

Popular

100/minute

25,000/month

50,000 credits

Higher rate limits

Priority support

All endpoints

Bulk operations

Enterprise

Custom

Custom credits

Custom rate limits

Dedicated support

SLA guarantee

White-label options

Per-Endpoint Rate Limits

Endpoint	Free Tier	Pro Tier	Enterprise	Credits
/v1/swiftsearch	10/min	100/min	Custom	1-2 per request
/v1/scrapeforge	5/min	50/min	Custom	2-5 per request
/v1/deepdive	2/min	20/min	Custom	5-15 per request

Rate Limit Headers

Every API response includes rate limit headers to help you track your usage:

Rate Limit Response Headers

JSON

{
  "x-ratelimit-limit": "1000",
  "x-ratelimit-remaining": "999", 
  "x-ratelimit-reset": "1640995200",
  "x-ratelimit-window": "3600"
}

Header Descriptions

x-ratelimit-limit

Total requests allowed per window

x-ratelimit-remaining

Requests remaining in current window

x-ratelimit-reset

Unix timestamp when window resets

x-ratelimit-window

Window duration in seconds

Best Practices

Always check remaining requests

Implement exponential backoff

Cache responses when possible

Monitor usage patterns

Handling Rate Limits

When you exceed rate limits, the API returns a 429 Too Many Requests status. Here's how to handle this gracefully:

Rate Limit Handling with Retry Logic

#!/bin/bash

API_KEY="sk_live_your_key_here"
MAX_RETRIES=3
RETRY_DELAY=1

make_request_with_retry() {
  local attempt=1
  
  while [ $attempt -le $MAX_RETRIES ]; do
    response=$(curl -s -w "%{http_code}" -X POST \
      https://www.searchhive.dev/api/v1/swiftsearch \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "test query", "max_results": 5}')
    
    http_code="${response: -3}"
    
    if [ "$http_code" = "429" ]; then
      echo "Rate limited. Waiting ${RETRY_DELAY} seconds..."
      sleep $RETRY_DELAY
      RETRY_DELAY=$((RETRY_DELAY * 2))
      attempt=$((attempt + 1))
    else
      echo "Status: $http_code"
      return 0
    fi
  done
  
  echo "Max retries exceeded"
  return 1
}

make_request_with_retry

Retry Strategy Tips

Use exponential backoff with jitter to avoid thundering herd problems. Start with 1 second delay, then 2s, 4s, etc. Always respect the x-ratelimit-reset header for accurate timing.

Credit Usage Monitoring

Track your credit usage to avoid hitting billing limits:

Monitor Your Credit Usage

curl -H "Authorization: Bearer $API_KEY" \
  https://www.searchhive.dev/api/v1/usage | \
  jq '{credits_used, credits_remaining, reset_date}'

Credit Exhaustion: When you run out of credits, API requests will return a 402 Payment Required status. Set up usage monitoring to avoid service interruption.

Rate Limit Status Codes

429 Too Many Requests

You've exceeded the rate limit for your plan. Wait before making more requests.

{"error": "Rate limit exceeded", "retry_after": 60}

402 Payment Required

Your credit balance is exhausted. Upgrade your plan or wait for the next billing cycle.

{"error": "Insufficient credits", "credits_remaining": 0}

Optimization Strategies

Batch Operations

Use bulk endpoints when available to reduce total requests:

Combine multiple URLs in ScrapeForge
Use higher max_results in SwiftSearch
Research multiple topics in DeepDive

Request Timing

Spread requests across time to avoid bursting:

Implement request queues
Use background processing
Schedule during off-peak hours