Rate Limiting

Understanding API rate limits and how to handle them effectively

StreetVerify implements rate limiting to ensure fair usage and maintain service quality for all users. This guide explains our rate limits and best practices for handling them.

Rate Limits

StreetVerify uses a Pay-As-You-Go model with consistent rate limiting:

  • Default Rate Limit: 100 requests per minute for all authenticated API requests
  • Autocomplete Endpoint: 200 requests per minute (higher limit for real-time suggestions)
  • Authentication Endpoints:
    • Signup: 5 requests per hour
    • Login: 20 requests per hour
    • Password Reset: 3 requests per hour

Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623456789

Header Definitions

  • X-RateLimit-Limit: Maximum requests allowed per minute
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets

Handling Rate Limits

429 Too Many Requests

When you exceed the rate limit, you’ll receive:

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

Best Practices

1. Implement Exponential Backoff

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        const delay = Math.min(1000 * Math.pow(2, i), 60000);
        
        console.log(`Rate limited. Retrying after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

2. Use Request Queuing

class RateLimitedQueue {
  constructor(requestsPerMinute) {
    this.queue = [];
    this.interval = 60000 / requestsPerMinute;
    this.processing = false;
  }
  
  async add(request) {
    return new Promise((resolve, reject) => {
      this.queue.push({ request, resolve, reject });
      if (!this.processing) this.process();
    });
  }
  
  async process() {
    this.processing = true;
    
    while (this.queue.length > 0) {
      const { request, resolve, reject } = this.queue.shift();
      
      try {
        const result = await request();
        resolve(result);
      } catch (error) {
        reject(error);
      }
      
      if (this.queue.length > 0) {
        await new Promise(r => setTimeout(r, this.interval));
      }
    }
    
    this.processing = false;
  }
}

// Usage
const queue = new RateLimitedQueue(50); // 50 requests per minute
const result = await queue.add(() => fetch(url, options));

3. Monitor Usage

class RateLimitMonitor {
  constructor() {
    this.requests = [];
  }
  
  trackRequest(headers) {
    this.requests.push({
      timestamp: Date.now(),
      remaining: parseInt(headers.get('X-RateLimit-Remaining')),
      limit: parseInt(headers.get('X-RateLimit-Limit'))
    });
    
    // Warn when approaching limit
    const usage = this.getUsagePercentage();
    if (usage > 80) {
      console.warn(`Rate limit usage at ${usage}%`);
    }
  }
  
  getUsagePercentage() {
    const latest = this.requests[this.requests.length - 1];
    if (!latest) return 0;
    
    return ((latest.limit - latest.remaining) / latest.limit) * 100;
  }
}

API Key Rate Limits

Each API key has a configurable rate limit:

  • Default: 100 requests per minute
  • Custom limits: Contact support to adjust rate limits for your specific needs
  • Rate limits are enforced per API key, not per account

Pricing Model

StreetVerify uses a simple Pay-As-You-Go pricing model:

  • $0.01 per API request for all endpoints
  • No monthly fees or subscriptions
  • Prepay for credits via crypto (USDT on Ethereum)
  • Minimum credit purchase: $50
  • All users get standard support

Increasing Rate Limits

If you need higher rate limits, please contact support@streetverify.com with:

  • Your current usage patterns
  • Expected request volume
  • Use case description

We can configure custom rate limits for your API keys based on your needs.

Rate Limit Best Practices

  1. Cache Responses: Store frequently accessed data locally
  2. Batch Operations: Process multiple items efficiently using client-side batching patterns
  3. Implement Retry Logic: Handle 429 responses gracefully
  4. Monitor Usage: Track your API usage in the dashboard

Error Handling Example

import time
import requests
from typing import Dict, Optional

class StreetVerifyClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://core.streetverify.com/api/v1"
        
    def make_request(self, endpoint: str, params: Dict, 
                    max_retries: int = 3) -> Optional[Dict]:
        """Make API request with rate limit handling."""
        
        headers = {"Authorization": f"Bearer {self.api_key}"}
        url = f"{self.base_url}/{endpoint}"
        
        for attempt in range(max_retries):
            response = requests.get(url, params=params, headers=headers)
            
            # Log rate limit status
            remaining = response.headers.get('X-RateLimit-Remaining', 'N/A')
            print(f"Rate limit remaining: {remaining}")
            
            if response.status_code == 200:
                return response.json()
                
            elif response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue
                
            else:
                response.raise_for_status()
                
        raise Exception("Max retries exceeded")

Monitoring Dashboard

Track your API usage in real-time:

  1. Log in to your StreetVerify Dashboard
  2. Navigate to Analytics
  3. View:
    • Current rate limit usage
    • Historical usage patterns
    • Per-endpoint breakdown
    • Rate limit violations

FAQ

What happens when I hit the rate limit?

You’ll receive a 429 status code with a Retry-After header indicating when you can retry.

Are rate limits per API key or per account?

Rate limits are applied per API key, allowing you to distribute load across multiple keys if needed.

Do failed requests count against my rate limit?

Yes, all requests including failed ones count toward your rate limit.

How is billing calculated?

Every successful API request costs $0.01. Failed requests (4xx/5xx errors) are not billed.

Can I have multiple API keys?

Yes, each account can have up to 10 active API keys.

Need Help?

Contact our support team at support@streetverify.com for:

  • Custom rate limit configuration
  • Technical assistance
  • Account questions