Rate Limiting Policy

To ensure fair usage, prevent abuse, and maintain high availability across all #about services, we enforce strict rate limits on all API endpoints. This page details current quotas, response headers, retry strategies, and architectural best practices.

Quota Tiers & Windows

Rate limits are evaluated per API key on a sliding 60-second window. Burst allowances accommodate short traffic spikes before throttling applies.

Response Headers

Every successful and error response includes telemetry headers to help you track consumption and predict resets:

HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 412
X-RateLimit-Reset: 1719823456
Retry-After: 18  
RateLimit-Policy: 600;w=60

• X-RateLimit-Limit: Maximum requests allowed per evaluation window
• X-RateLimit-Remaining: Available requests left in the current window
• X-RateLimit-Reset: Unix epoch timestamp when the quota refreshes
• Retry-After: Recommended wait time in seconds (RFC 6585)
• RateLimit-Policy: IETF draft format for algorithmic parsing

429 Too Many Requests

When your application exceeds the configured threshold, the gateway returns a 429 status code. The response body contains a machine-readable error object:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the allowed request quota for this window.",
    "retry_after": 14,
    "documentation_url": "/rate-limiting"
  }
}

Retry Strategy & Backoff

Recommended implementation for resilient clients:

async function requestWithBackoff(url, opts, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, opts);
    
    if (res.status === 429) {
      const delay = Math.min(
        Math.pow(2, attempt) * 1000 + Math.random() * 500,
        30000
      );
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    return res;
  }
  throw new Error('Rate limit exhausted after retries');
}

Architectural Best Practices

• Cache Aggressively: Use Cache-Control and CDN layers to minimize redundant calls
• Batch Operations: Prefer /v1/bulk endpoints over sequential single-resource requests
• Use Webhooks: Replace polling with server-sent events or webhook subscriptions for state changes
• Key Isolation: Separate API keys for dev, staging, and production to avoid quota bleed
• Monitor Proactively: Set alerts at 80% quota consumption to scale before throttling occurs