Copy page

API Guides

Rate Limiting & Quotas

API Codex implements rate limiting to ensure fair usage and maintain service quality for all users. This guide explains how rate limiting works and how to handle it effectively.

Overview

Rate limiting protects our APIs from abuse and ensures reliable performance for all users. Your plan sets two limits:

• Requests per second (RPS), enforced in real time
• Monthly credits, the total request budget across all 40 APIs

Plans and Limits

Rate Limits by Plan

Plan	Price	Monthly Credits	Requests/Second
Free	$0	1,000	2 RPS
Starter	$29.99/mo	50,000	10 RPS
Pro	$99.99/mo	250,000	25 RPS

Note: limits are per account, not per API. One key works across all 40 APIs, and every plan draws from the same credit balance. Credit cost per request varies by API: 1 credit for bundled data and edge lookups, 5 for live network lookups, 25 for AI and scraping APIs. Only successful (2xx) responses consume credits. Manage your plan at dash.apicodex.io/billing.

Rate Limit Headers

All API responses include headers that inform you about your current rate limit status:

Standard Headers

Code
x-ratelimit-requests-limit: 1000
x-ratelimit-requests-remaining: 847
x-ratelimit-requests-reset: 1640995200

Header	Description	Example
x-ratelimit-requests-limit	Total requests allowed in current window	1000
x-ratelimit-requests-remaining	Requests remaining in current window	847
x-ratelimit-requests-reset	Unix timestamp when limit resets	1640995200

Reading Rate Limit Headers

Code
const rateLimit = {
  limit: parseInt(response.headers.get('x-ratelimit-requests-limit')),
  remaining: parseInt(response.headers.get('x-ratelimit-requests-remaining')),
  reset: parseInt(response.headers.get('x-ratelimit-requests-reset'))
};

// Warn if approaching limit (< 10% remaining)
if (rateLimit.remaining < rateLimit.limit * 0.1) {
  console.warn('Approaching rate limit!');
}

Handling Rate Limits

429 Too Many Requests

When you exceed your rate limit, you'll receive a 429 status code:

Code
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after some time.",
  "retryAfter": 60
}

Implementing Retry Logic

Exponential Backoff

Code
async function executeWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await requestFn();

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : 1000 * Math.pow(2, attempt) + Math.random() * 1000;

      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Request Queue Management

For bulk operations, implement a request queue that:

• Tracks requests per time window
• Waits when limit is reached
• Processes requests in order

Rate Limiting Strategies

1. Client-Side Throttling

Track requests in a sliding window and wait if limit is reached before making new requests.

2. Adaptive Rate Limiting

Adjust request rate based on remaining quota:

• > 80% used: Slow down significantly
• < 20% used: Can increase rate
• 0 remaining: Wait until reset

3. Circuit Breaker Pattern

After multiple rate limit errors:

• CLOSED → Normal operation
• OPEN → Reject requests immediately, wait for timeout
• HALF-OPEN → Test with one request, recover or stay open

Optimization Techniques

1. Request Batching

Combine multiple operations where possible. Check if the API supports batch endpoints.

2. Response Caching

Cache responses with appropriate TTLs to reduce API calls:

• DNS lookups: 24 hours (respect TTL from response)
• Email validation: 1 hour
• Text analysis: 30 minutes

3. Parallel Processing with Limits

Process multiple requests in parallel, but limit concurrency to avoid overwhelming the API. Use Promise.race() to maintain a pool of active requests.

Monitoring & Alerts

Set up monitoring to track rate limit usage:

Alert Level	Condition	Action
Warning	> 80% usage	Review request patterns
Critical	0 remaining	Reduce request rate, investigate

Track metrics like average usage, peak usage, and requests per minute to identify patterns and optimize your usage.

Best Practices

Do's ✅

1. Always check rate limit headers in responses
2. Implement exponential backoff for retries
3. Cache responses when appropriate
4. Use request queuing for bulk operations
5. Monitor your usage proactively
6. Implement circuit breakers for resilience
7. Batch requests when possible

Don'ts ❌

1. Don't ignore 429 responses - Always handle them
2. Don't retry immediately - Use backoff strategies
3. Don't hammer the API - Respect rate limits
4. Don't hardcode delays - Use adaptive timing
5. Don't waste quota - Cache when possible

Upgrading Your Plan

If you consistently hit rate limits, consider upgrading:

1. Monitor your usage patterns in the dashboard
2. Calculate required capacity
3. Visit dash.apicodex.io/billing
4. Select the appropriate plan
5. Upgrade takes effect immediately, with no code changes and the same API key

Next Steps

• Learn about Error Handling for robust applications
• Review Best Practices for production deployments
• Explore Authentication for secure API access
• Browse our API Catalog to start building