Rate Limits

Rate Limiting Overview

Fetchin implements two types of rate limiting to ensure fair usage and system stability:

Per-second rate limit: Configurable per plan (default: 5 requests per second)
Monthly quota: Based on your plan (1,000 for Trial, custom for Enterprise)

Rate Limit Structure

Per-Second Limit

Plan-basedTrial: 5 requests/second Enterprise: Custom RPS

Monthly Quota

Plan-basedTrial: 1,000 credits/month Enterprise: Custom

Per-Second Rate Limit

Your per-second rate limit depends on your plan. Trial plans have a default of 5 requests per second, while Enterprise plans can have custom limits.

How It Works

Requests are counted using a sliding window algorithm
After exceeding your RPS limit, subsequent requests return 429
The limit applies to your whole account, across all endpoints. All of your API keys share it — creating additional keys does not add capacity
Most endpoints cost 1 unit per request; /post/engagement costs 2 units, so your plan’s per-second limit must be at least 2 to call it
Your specific RPS limit is visible in your dashboard

Example (with 5 RPS limit)

Second 1: 5 requests ✅ (all succeed)
Second 1: 6th request ❌ (429 error)
Second 2: 5 requests ✅ (window slides, all succeed)

Your RPS limit applies across ALL your requests. If you make 5 profile requests in one second (with a 5 RPS limit), you cannot make any posts requests until the window slides.

Monthly Quota Limiting

Total credits allowed per month based on your plan:

Trial Plan: 1,000 credits/month
Enterprise Plan: Custom limits

How It Works

Each successful API request consumes the credits its endpoint costs, which is 1 for every endpoint except /post/engagement at 2
A 404 not found consumes 1 credit
Every other failure is free: 400, 401, 403, 429, 402 itself and any 5xx on our side
Quota resets on your renewal date (monthly anniversary of signup)
Unused credits do NOT carry over to next month

Handling Rate Limit Errors

429 vs 402

The two limits return different HTTP statuses so you can tell them apart from the status line alone (the code field carries the same distinction): Per-second limit exceeded — 429 Too Many Requests (code: "RATE_LIMITED"). Back off and retry, honoring the Retry-After header (seconds):

{
  "error": "Rate limit exceeded. Try again later.",
  "code": "RATE_LIMITED"
}

Monthly quota exhausted — 402 Payment Required (code: "QUOTA_EXHAUSTED"). Upgrade your plan or wait for renewal; retrying won’t help until then, and there is no Retry-After:

{
  "error": "Quota exceeded. Upgrade your plan or wait for renewal.",
  "code": "QUOTA_EXHAUSTED"
}

Response Headers

Each API response includes rate limit headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1704067201

X-RateLimit-Limit: Requests allowed per second (5)
X-RateLimit-Remaining: Requests remaining this second
X-RateLimit-Reset: Unix timestamp when limit resets

Rate limit headers show per-second limits. Check your dashboard for both your RPS limit and monthly quota information.

Enterprise plans can request custom RPS limits. Contact sales if you need higher throughput for your application.

Best Practices

1. Respect Your RPS Limit

Space out your requests to stay under your rate limit (default: 5 per second for Trial plans):

async function fetchMultipleProfiles(profileUrls, apiKey) {
  const delay = 200; // 200ms = 5 req/s max
  const results = [];
  
  for (const url of profileUrls) {
    const response = await fetch(
      `https://api.fetchin.io/api/v1/profile?profileUrlOrUrn=${url}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    
    results.push(await response.json());
    
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  return results;
}

import time
import requests

def fetch_multiple_profiles(profile_urls, api_key):
    delay = 0.2  # 200ms = 5 req/s max
    results = []
    
    for url in profile_urls:
        response = requests.get(
            'https://api.fetchin.io/api/v1/profile',
            headers={'X-API-Key': api_key},
            params={'profileUrlOrUrn': url}
        )
        
        results.append(response.json())
        time.sleep(delay)
    
    return results

2. Implement Retry Logic with Backoff

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 waitTime = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

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:
            wait_time = (2 ** i) * 1
            time.sleep(wait_time)
            continue
            
        return response
    
    raise Exception('Max retries exceeded')

3. Use Concurrency Control

Limit concurrent requests to respect the rate limit:

class RateLimiter {
  constructor(maxPerSecond = 5) {
    this.maxPerSecond = maxPerSecond;
    this.queue = [];
    this.processing = 0;
    this.lastReset = Date.now();
    this.requestsThisSecond = 0;
  }
  
  async add(fn) {
    while (this.requestsThisSecond >= this.maxPerSecond) {
      const now = Date.now();
      const timeSinceReset = now - this.lastReset;
      
      if (timeSinceReset >= 1000) {
        this.requestsThisSecond = 0;
        this.lastReset = now;
      } else {
        await new Promise(resolve => 
          setTimeout(resolve, 1000 - timeSinceReset)
        );
      }
    }
    
    this.requestsThisSecond++;
    return await fn();
  }
}

const limiter = new RateLimiter(5);

await limiter.add(() => fetchProfile(url1));
await limiter.add(() => fetchProfile(url2));

4. Check Quota Before Bulk Operations

Before processing large batches:

Check remaining quota in dashboard
Calculate how many requests you need
Process in chunks if quota is low

3. Queue Requests

For high-volume applications, implement a request queue:

class RequestQueue {
  constructor(maxConcurrent = 5) {
    this.maxConcurrent = maxConcurrent;
    this.running = 0;
    this.queue = [];
  }
  
  async add(fn) {
    if (this.running >= this.maxConcurrent) {
      await new Promise(resolve => this.queue.push(resolve));
    }
    
    this.running++;
    
    try {
      return await fn();
    } finally {
      this.running--;
      const resolve = this.queue.shift();
      if (resolve) resolve();
    }
  }
}

5. Cache Aggressively

Store results to avoid repeat requests:

const cache = new Map();

async function getCachedProfile(profileUrl, apiKey) {
  if (cache.has(profileUrl)) {
    return cache.get(profileUrl);
  }
  
  const response = await fetch(
    `https://api.fetchin.io/api/v1/profile?profileUrlOrUrn=${profileUrl}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  
  const data = await response.json();
  cache.set(profileUrl, data);
  
  return data;
}

Common Scenarios

Batch Processing

Processing 100 profiles at 5 req/s:

100 profiles ÷ 5 req/s = 20 seconds minimum

Add buffer time for network latency and processing:

Estimated time: 22-25 seconds

Real-Time Applications

For real-time applications making frequent requests:

Implement request queuing
Use websockets for updates when possible
Cache frequently accessed data
Batch multiple data points into single requests

If you need higher rate limits for your use case, contact sales for an Enterprise plan with custom limits.

Error Responses

429 Too Many Requests (Per-Second)

{
  "error": "Rate limit exceeded. Try again later.",
  "code": "RATE_LIMITED"
}

Cause: Exceeded your per-second rate limit Solution:

Wait 1 second before retrying
Implement request spacing based on your RPS limit
Use rate limiting library

402 Payment Required (Monthly Quota)

{
  "error": "Quota exceeded. Upgrade your plan or wait for renewal.",
  "code": "QUOTA_EXHAUSTED"
}

Cause: Monthly quota depleted Solution:

Wait for quota renewal
Upgrade to a higher quota plan
Buy pay-as-you-go credits, available on request from support

Monitoring

Track your rate limit compliance:

Dashboard - View daily usage patterns and monthly quota
Error rate - Monitor 429 (rate limit) and 402 (quota exhausted) errors
Response headers - Check X-RateLimit-* headers in responses
Success rate - Ensure efficient request usage

Neither a 429 nor a 402 consumes credits. Being throttled and being out of credits are both free, so a retry storm costs you nothing but time. The only failing response that consumes a credit is a 404. See Quotas for the full breakdown.

Getting Started

Core Concepts

Apify Compatibility

Account

Posts

Profile

Company

Rate Limiting Overview

Rate Limit Structure

Per-Second Limit

Monthly Quota

Per-Second Rate Limit

How It Works

Example (with 5 RPS limit)

Monthly Quota Limiting

How It Works

Handling Rate Limit Errors

429 vs 402

Response Headers

Best Practices

1. Respect Your RPS Limit

2. Implement Retry Logic with Backoff

3. Use Concurrency Control

4. Check Quota Before Bulk Operations

3. Queue Requests

5. Cache Aggressively

Common Scenarios

Batch Processing

Real-Time Applications

Error Responses

429 Too Many Requests (Per-Second)

402 Payment Required (Monthly Quota)

Monitoring

​Rate Limiting Overview

​Rate Limit Structure

Per-Second Limit

Monthly Quota

​Per-Second Rate Limit

​How It Works

​Example (with 5 RPS limit)

​Monthly Quota Limiting

​How It Works

​Handling Rate Limit Errors

​429 vs 402

​Response Headers

​Best Practices

​1. Respect Your RPS Limit

​2. Implement Retry Logic with Backoff

​3. Use Concurrency Control

​4. Check Quota Before Bulk Operations

​3. Queue Requests

​5. Cache Aggressively

​Common Scenarios

​Batch Processing

​Real-Time Applications

​Error Responses

​429 Too Many Requests (Per-Second)

​402 Payment Required (Monthly Quota)

​Monitoring

Rate Limiting Overview

Rate Limit Structure

Per-Second Rate Limit

How It Works

Example (with 5 RPS limit)

Monthly Quota Limiting

How It Works

Handling Rate Limit Errors

429 vs 402

Response Headers

Best Practices

1. Respect Your RPS Limit

2. Implement Retry Logic with Backoff

3. Use Concurrency Control

4. Check Quota Before Bulk Operations

3. Queue Requests

5. Cache Aggressively

Common Scenarios

Batch Processing

Real-Time Applications

Error Responses

429 Too Many Requests (Per-Second)

402 Payment Required (Monthly Quota)

Monitoring