Rate Limits

Overview

World Monitor implements IP-based rate limiting to ensure fair usage and protect against abuse. Rate limits are enforced using Upstash Redis with a sliding window algorithm.

Rate Limit Details

Global Rate Limit

All API endpoints share a single global rate limit:

limit

number

default:"300"

Maximum requests per window

window

string

default:"60 s"

Sliding window duration (60 seconds)

Default: 300 requests per 60 seconds (5 requests/second average)

Rate Limit Algorithm

Upstash Ratelimit uses a sliding window algorithm:

new Ratelimit({
  redis: new Redis({ url, token }),
  limiter: Ratelimit.slidingWindow(300, '60 s'),
  prefix: 'rl',
  analytics: false,
});

Sliding Window Benefits:

Smooth rate limiting (no burst at window boundaries)
More accurate than fixed windows
Prevents “thundering herd” at window reset

IP Address Detection

Rate limits are applied per client IP address. The API uses the following priority:

x-real-ip - Vercel/Cloudflare TCP connection IP (cannot be spoofed)
cf-connecting-ip - Cloudflare connecting IP
x-forwarded-for - First IP in chain (less trusted)
Fallback: 0.0.0.0

The x-forwarded-for header can be client-settable. The API prioritizes x-real-ip from trusted infrastructure to prevent spoofing.

function getClientIp(request: Request): string {
  return (
    request.headers.get('x-real-ip') ||
    request.headers.get('cf-connecting-ip') ||
    request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
    '0.0.0.0'
  );
}

Rate Limit Headers

All API responses include rate limit information in headers:

X-RateLimit-Limit

string

Maximum requests allowed in the window (e.g., “300”)

X-RateLimit-Remaining

string

Requests remaining in current window

X-RateLimit-Reset

string

Unix timestamp (milliseconds) when the window resets

Retry-After

string

Seconds to wait before retrying (only on 429 responses)

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709654432000

Rate Limit Exceeded

When the rate limit is exceeded, the API returns: Status Code: 429 Too Many Requests Response Body:

{
  "error": "Too many requests"
}

Response Headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709654432000
Retry-After: 42
Content-Type: application/json

Handling 429 Responses

const response = await fetch('https://worldmonitor.app/api/market/v1/list-market-quotes');

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After'));
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  
  // Wait and retry
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // ... retry request
}

Upstash Integration

Rate limiting is powered by Upstash Redis, a serverless Redis service optimized for edge functions.

Configuration

Rate limiting requires two environment variables:

UPSTASH_REDIS_REST_URL=https://your-redis-instance.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here

If Upstash credentials are not configured, rate limiting is disabled and all requests are allowed.

Implementation

import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: new Redis({ 
    url: process.env.UPSTASH_REDIS_REST_URL,
    token: process.env.UPSTASH_REDIS_REST_TOKEN 
  }),
  limiter: Ratelimit.slidingWindow(300, '60 s'),
  prefix: 'rl',
  analytics: false,
});

const { success, limit, reset } = await ratelimit.limit(clientIp);

Rate Limit Storage

Upstash stores rate limit counters with:

Key prefix: rl (configurable)
Key format: rl:{ip-address}
TTL: Automatically managed by sliding window
Analytics: Disabled for performance

Best Practices

1. Implement Exponential Backoff

async function fetchWithBackoff(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    
    if (response.status !== 429) {
      return response;
    }
    
    const retryAfter = parseInt(response.headers.get('Retry-After')) || 1;
    const backoff = retryAfter * Math.pow(2, i);
    
    await new Promise(resolve => setTimeout(resolve, backoff * 1000));
  }
  
  throw new Error('Max retries exceeded');
}

2. Monitor Rate Limit Headers

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const limit = parseInt(response.headers.get('X-RateLimit-Limit'));

if (remaining < limit * 0.1) {
  console.warn(`Approaching rate limit: ${remaining}/${limit} remaining`);
}

3. Batch Requests

Use batch endpoints when available:

// ❌ Multiple requests
for (const icao of icaos) {
  await fetch(`/api/military/v1/get-aircraft-details?icao24=${icao}`);
}

// ✅ Single batch request
await fetch('/api/military/v1/get-aircraft-details-batch', {
  method: 'POST',
  body: JSON.stringify({ icao24s: icaos })
});

4. Use Edge Caching

Leverage built-in edge caching for cacheable endpoints:

// Cached at edge (fast tier: 2 min)
fetch('/api/market/v1/list-market-quotes')

// Static data (1 hour cache)
fetch('/api/wildfire/v1/list-fire-detections')

Cached responses don’t count against your rate limit after the first request in the cache window.

Rate Limit Exemptions

The following scenarios are exempt from rate limiting:

Failed authentication (401/403) - Returns before rate limit check
OPTIONS preflight requests - CORS preflight doesn’t consume quota
Upstash unavailable - Rate limiting is disabled if Redis is unreachable

Error Handling

If Upstash Redis is unavailable:

try {
  const { success, limit, reset } = await ratelimit.limit(ip);
  // ... handle rate limit
} catch (error) {
  // Redis error - allow request through
  console.error('Rate limit check failed:', error);
  return null; // No rate limit response
}

Rate limiting gracefully degrades. If Upstash is unavailable, requests are allowed through to prevent service disruption.

Increasing Rate Limits

The default rate limit (300 req/min) is designed for typical usage. If you need higher limits:

Contact Support: Reach out to the World Monitor team
Provide Justification: Explain your use case and expected load
Custom Configuration: Receive dedicated rate limit tier

Enterprise users can receive custom rate limits configured per API key.

Monitoring and Analytics

Rate limit metrics are available:

Response Headers: Real-time limit/remaining/reset info
429 Responses: Track rate limit exceeded events
Upstash Dashboard: View Redis usage and performance (if enabled)

Analytics are currently disabled (analytics: false) for performance. This may be enabled in future versions.

Overview

Services

Data Sources

Overview

Rate Limit Details

Global Rate Limit

Rate Limit Algorithm

IP Address Detection

Rate Limit Headers

Example Response Headers

Rate Limit Exceeded

Handling 429 Responses

Upstash Integration

Configuration

Implementation

Rate Limit Storage

Best Practices

1. Implement Exponential Backoff

2. Monitor Rate Limit Headers

3. Batch Requests

4. Use Edge Caching

Rate Limit Exemptions

Error Handling

Increasing Rate Limits

Monitoring and Analytics

Next Steps

Authentication

API Reference

Build docs developers (and LLMs) love

Overview

Services

Data Sources

​Overview

​Rate Limit Details

​Global Rate Limit

​Rate Limit Algorithm

​IP Address Detection

​Rate Limit Headers

​Example Response Headers

​Rate Limit Exceeded

​Handling 429 Responses

​Upstash Integration

​Configuration

​Implementation

​Rate Limit Storage

​Best Practices

​1. Implement Exponential Backoff

​2. Monitor Rate Limit Headers

​3. Batch Requests

​4. Use Edge Caching

​Rate Limit Exemptions

​Error Handling

​Increasing Rate Limits

​Monitoring and Analytics

​Next Steps

Authentication

API Reference

Build docs developers (and LLMs) love

Overview

Rate Limit Details

Global Rate Limit

Rate Limit Algorithm

IP Address Detection

Rate Limit Headers

Example Response Headers

Rate Limit Exceeded

Handling 429 Responses

Upstash Integration

Configuration

Implementation

Rate Limit Storage

Best Practices

1. Implement Exponential Backoff

2. Monitor Rate Limit Headers

3. Batch Requests

4. Use Edge Caching

Rate Limit Exemptions

Error Handling

Increasing Rate Limits

Monitoring and Analytics

Next Steps