Working With Rate Limits

A rate limit is like having a bucket with a limited number of tokens. Each API request uses one token from your bucket. The bucket refills with new tokens over time, but if you use all your tokens, you’ll need to wait for more to be added before making additional requests.

How Rate Limits Work

Think of rate limiting like a water faucet with a flow regulator:

1. Token Bucket: You start with a full bucket of 100 request tokens
2. Request Consumption: Each API call uses one token from your bucket
3. Bucket Refill: Your bucket refills completely every 60 seconds
4. Overflow Protection: If your bucket is empty, you must wait for it to refill before making more requests

The system tracks your usage in real-time and provides information about your current status through response headers.

Per-API-Key Tracking

Rate limits are tracked individually for each API key, so one application’s usage doesn’t affect another’s limits.

Tracking Your Usage

Every API response includes headers that tell you about your current rate limit status:

Response Headers

X-RateLimit-Limit
The total number of requests allowed in the current time window.

X-RateLimit-Limit: 100

X-RateLimit-Remaining
The number of requests you have left in the current time window.

X-RateLimit-Remaining: 75

X-RateLimit-Reset
A Unix timestamp indicating when your rate limit will reset (when your bucket refills).

X-RateLimit-Reset: 1672531200

Retry-After (when rate limited)
When you exceed your rate limit, this header tells you how many seconds to wait before trying again.

Retry-After: 30

Example Response Headers

Here’s what you might see in a successful response:

1
HTTP/1.1 200 OK
2
X-RateLimit-Limit: 100
3
X-RateLimit-Remaining: 45
4
X-RateLimit-Reset: 1672531200
5
Content-Type: application/json
6
7
{
8
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
9
  "email": "user@example.com"
10
}

When You Exceed Rate Limits

If you make too many requests and exceed your rate limit, you’ll receive a 429 Too Many Requests response:

1
HTTP/1.1 429 Too Many Requests
2
X-RateLimit-Limit: 100
3
X-RateLimit-Remaining: 0
4
X-RateLimit-Reset: 1672531200
5
Retry-After: 45
6
Content-Type: application/json
7
8
{
9
  "error": "Too many requests"
10
}

This response tells you:

• You’ve used all 100 of your allowed requests
• You have 0 requests remaining
• Your limit will reset at timestamp 1672531200
• You should wait 45 seconds before making another request

Working with Rate Limits In Your App

Monitor Your Usage

Always check the rate limit headers in your responses to monitor your usage:

1
const response = await fetch("https://api.fanvue.com/users/me", {
2
  headers: {
3
    "X-Fanvue-API-Key": process.env.FANVUE_API_KEY,
4
  },
5
});
6
7
const limit = response.headers.get("X-RateLimit-Limit");
8
const remaining = response.headers.get("X-RateLimit-Remaining");
9
const reset = response.headers.get("X-RateLimit-Reset");
10
11
console.log(`Rate limit: ${remaining}/${limit} requests remaining`);
12
console.log(`Resets at: ${new Date(parseInt(reset) * 1000)}`);

Handle Rate Limit Errors

Implement proper error handling for rate limit responses:

1
async function makeAPIRequest(url) {
2
  const response = await fetch(url, {
3
    headers: {
4
      "X-Fanvue-API-Key": process.env.FANVUE_API_KEY,
5
    },
6
  });
7
8
  if (response.status === 429) {
9
    const retryAfter = response.headers.get("Retry-After");
10
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
11
12
    // Wait and retry
13
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
14
    return makeAPIRequest(url);
15
  }
16
17
  return response.json();
18
}

Best Practices

Implement Exponential Backoff
When you hit rate limits, wait progressively longer between retry attempts.

Batch Your Requests
If possible, combine multiple operations into fewer API calls.

Cache Responses
Store API responses locally to reduce the number of requests you need to make.

Monitor Continuously
Keep track of your rate limit headers to avoid hitting limits unexpectedly.

Plan for Peak Usage
Consider your application’s peak usage patterns and design accordingly.

Python Example

1
import requests
2
import time
3
import os
4
5
def make_request_with_retry(url, max_retries=3):
6
    headers = {
7
        'X-Fanvue-API-Key': os.getenv('FANVUE_API_KEY')
8
    }
9
10
    for attempt in range(max_retries + 1):
11
        response = requests.get(url, headers=headers)
12
13
        # Check rate limit headers
14
        remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
15
        print(f"Requests remaining: {remaining}")
16
17
        if response.status_code == 429:
18
            if attempt < max_retries:
19
                retry_after = int(response.headers.get('Retry-After', 60))
20
                print(f"Rate limited. Waiting {retry_after} seconds...")
21
                time.sleep(retry_after)
22
                continue
23
            else:
24
                raise Exception("Max retries exceeded")
25
26
        return response.json()