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)
Credit balance: your subscription’s monthly allowance, plus any pay-as-you-go credits you have bought

Rate Limit Structure

Per-Second Limit

Plan-basedSelf-serve: 5 requests/second Dedicated: 10 to 100+, on request

Credit Balance

Plan allowance + pay as you goFree: 1,000 credits, once Subscription: 50,000 to 2,000,000 a month Pay as you go: bought outright, valid 12 months

These two limits are independent axes. Buying credits never raises your requests per second, and a higher rate limit never adds credits.

Per-Second Rate Limit

Your per-second rate limit depends on your plan. Everything self-serve — free, subscription and pay as you go alike — runs at 5 requests per second. Higher throughput, from 10 to 100+, runs on dedicated capacity set up with our team.

How It Works

Requests are counted using a sliding window algorithm
The window is two seconds wide and holds twice your per-second limit, so your sustained rate is exactly your RPS and short bursts above it are absorbed rather than refused. This is deliberate: with a one-second window, a client pacing at exactly its limit loses every request that lands a few milliseconds early, and the lost slot can never be recovered because catching up means briefly exceeding the rate
Pushing harder does not raise your sustained rate. Twice the limit over two seconds is still your limit per second, so a client hammering flat out settles at exactly the RPS it pays for
Once the window is full, further 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. Rate-limit units are counted separately from credits, so an endpoint priced differently in credits still costs its own number of units — check its reference page. /profile with fullProfile=true is one of those: 2 credits, but still 1 unit
/company/batch takes 1 unit per company: one when the request arrives, then one more for each company after the first, drawn from the same budget as it works through the batch. A 50-company batch on a 5 RPS plan takes about 10 seconds, like 50 separate calls
/posts/search costs 1 unit like most endpoints, but additionally caps concurrency: how many of your searches may be running at the same moment. That allowance follows your plan’s per-second limit, set so that sending your plan’s rate does not reach it. See Concurrency limits
Your specific RPS limit is visible in your dashboard

Example (with 5 RPS limit)

A 5 RPS plan has a window two seconds wide holding 10 units:

t = 0.0s   10 requests  ✅ (the whole window budget, in one burst)
t = 0.0s   11th request ❌ (429, window full, Retry-After: 2)
t = 2.0s   10 requests  ✅ (the first 10 have just aged out)

Sustained: 10 requests every 2 seconds = exactly 5/s.

Units age out individually, two seconds after the request that used them — the window slides continuously rather than emptying all at once. Spread those same 10 requests across the first second and they come back one by one across the third, not in a block.

Your RPS limit applies across ALL your requests and all your API keys. Spending the burst on profile requests means posts requests wait until the window slides.

The burst absorbs jitter, it does not add capacity. If you are not reaching your rate, the usual cause is concurrency, not the limit: a worker that waits for each response can only start a new request every round trip, so N workers produce at most N / latency requests per second. With a 1.2s median response time, 10 workers top out near 8 req/s whatever your plan says. Size your in-flight requests to rate x latency and you will reach your rate. Going far beyond that does not buy more throughput, it only converts the excess into 429s.

The One Exception: Account Endpoints

GET /api/v1/subscription is metered on its own budget of 1 request per second per account, not on your plan’s. Checking your balance therefore costs you nothing in throughput: the response carries X-RateLimit-Cost: 0, and your plan’s per-second window is untouched however often you poll. GET /api/v1/usage works the same way, on a 1 request per second budget of its own: polling one never slows the other. The two budgets are independent in both directions. Going over 1 req/s on that endpoint returns 429 even when your plan budget is entirely free, and exhausting your plan budget does not stop you reading your balance — which is the point, since that is exactly the moment you need to know why calls are failing. Because the call spends none of the plan window, it cannot report what is left of it: that response carries no X-RateLimit-Remaining or X-RateLimit-Reset. X-RateLimit-Limit still shows your plan’s RPS. Pace your data calls from the headers your data calls return — see below.

Concurrency Limits

Your per-second limit counts request starts. One endpoint also caps how many of your requests may be in flight at the same moment: POST /api/v1/posts/search. That allowance is derived from your own per-second rate limit, generously, and not a flat number: it follows your plan, and it is set so that a client sending the rate it pays for never reaches it. The two limits are different things, because a search page is held open for seconds rather than milliseconds — so a client that fires searches in parallel far faster than its rate implies can sit inside its RPS limit and still collect 429s from this cap. Going over it returns 429 RATE_LIMITED with Retry-After: 1 and costs 0 credits:

{
  "error": "Too many searches running at once for your account. This endpoint holds each search open for several seconds, so a burst can exceed your plan even when your request rate does not. Wait for one to finish and retry.",
  "code": "RATE_LIMITED"
}

If you see it, you have many more searches open at once than your rate implies: lower your concurrency and honour Retry-After. Where an endpoint carries a cap like this, it is stated on its own reference page; pace everything else from your rate alone.

Credit Balance Limiting

A subscription sets the credits you get each month, from 50,000 to 2,000,000 self-serve. A new account instead gets 1,000 free credits once, at sign-up, which are never topped up again. On top of either you can hold pay-as-you-go credits — bought outright from the dashboard, valid 12 months from purchase, usable with or without a subscription.

How It Works

Each successful API request consumes the credits its endpoint costs, which is 1 for every endpoint listed in this documentation except /post/engagement at 2 and /profile with fullProfile=true at 2 (1 when its extra page could not be read) — unless an endpoint’s own reference page states otherwise
A 404 not found consumes 1 credit
Every other failure is free: 400, 401, 403, 410, 429, 402 itself and any 5xx on our side
Requests spend your plan allowance first, then your pay-as-you-go credits, soonest expiry first
A subscription’s allowance resets on its renewal date; the free sign-up credits never reset
Unused plan credits do NOT carry over to next month — but pay-as-you-go credits do: they are untouched by a renewal and live 12 months from their own purchase

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"
}

Credits exhausted — 402 Payment Required (code: "QUOTA_EXHAUSTED"), normally meaning both your plan allowance and your pay-as-you-go credits are empty; on an endpoint that can cost more than one credit per request, also when what is left is smaller than that request’s price (see Quotas). Buy pay-as-you-go credits, 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

Every /api/v1/* response — success or error — carries your current rate-limit and credit state, so you can pace a batch without making a second call. The credit headers are on every response without exception, including 402 and 429; the two X-RateLimit-Remaining / -Reset headers are on every response that spends plan budget, which is all of them but GET /api/v1/subscription and GET /api/v1/usage:

X-RateLimit-Limit: 5
X-RateLimit-Cost: 1
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1704067201
X-Credits-Remaining: 48210
X-Credits-Subscription-Remaining: 48210
X-Credits-Payg-Remaining: 0

X-RateLimit-Limit: RPS units allowed per second on your plan
X-RateLimit-Cost: units this endpoint consumes (1 for most endpoints)
X-RateLimit-Remaining: units still free in the current window, capped at your per-second limit (the window holds more, so this understates the burst available rather than overstating it)
X-RateLimit-Reset: Unix timestamp at which the next unit frees up
X-Credits-Remaining: total credits left (plan allowance + pay as you go)
X-Credits-Subscription-Remaining: credits left on your plan allowance
X-Credits-Payg-Remaining: pay-as-you-go credits left

Budget is counted in units, not requests, because a few endpoints cost more than one. The check to make before firing is therefore X-RateLimit-Remaining >= X-RateLimit-Cost, not > 0:

const remaining = Number(res.headers.get('X-RateLimit-Remaining'));
const cost = Number(res.headers.get('X-RateLimit-Cost'));
if (remaining < cost) {
  // Wait until X-RateLimit-Reset before sending the next call.
}

The window slides: it is the last 2,000 ms, not a bucket that empties on the second boundary. X-RateLimit-Reset is therefore the soonest moment a unit frees up, not the start of a fresh allowance.Credit balances are read as the request is admitted and settle asynchronously, so treat them as accurate to within a few seconds rather than exact. For an authoritative figure — including your renewal date and credit expiry — call GET /api/v1/subscription, which is free and never consumes a credit.Requests rejected for a missing or invalid API key (401) carry no headers, because the account is not yet known at that point.

Dedicated plans carry 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 (5 per second on every self-serve plan):

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 your remaining credits, in the dashboard or with GET /api/v1/subscription (creditsRemaining covers both balances together)
Calculate how many credits the batch needs
Top up with pay-as-you-go credits, or process in chunks, if the balance is short

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 a dedicated 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 for the number of seconds in the Retry-After header before retrying. Do not assume one second: the window is two seconds wide, so a burst you sent all at once can take that long to clear
Implement request spacing based on your RPS limit
Use a rate limiting library

402 Payment Required (Out of Credits)

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

Cause: Every credit balance is empty — the plan allowance for this period is spent and no pay-as-you-go credits are left — or, on an endpoint that prices a request above one credit, the balance left is smaller than what that request costs Solution:

Buy pay-as-you-go credits, self-serve from fetchin.io/credits — usable within seconds and no code change
Wait for your plan allowance to renew
Upgrade to a plan with a higher allowance (the only option that also raises your RPS)

Monitoring

Track your rate limit compliance:

Dashboard - View daily usage patterns, your plan allowance and your pay-as-you-go balance
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

Credit Balance

Per-Second Rate Limit

How It Works

Example (with 5 RPS limit)

The One Exception: Account Endpoints

Concurrency Limits

Credit Balance 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 (Out of Credits)

Monitoring

​Rate Limiting Overview

​Rate Limit Structure

Per-Second Limit

Credit Balance

​Per-Second Rate Limit

​How It Works

​Example (with 5 RPS limit)

​The One Exception: Account Endpoints

​Concurrency Limits

​Credit Balance 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 (Out of Credits)

​Monitoring

Rate Limiting Overview

Rate Limit Structure

Per-Second Rate Limit

How It Works

Example (with 5 RPS limit)

The One Exception: Account Endpoints

Concurrency Limits

Credit Balance 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 (Out of Credits)

Monitoring