Documentation

API Rate Limiting

Learn how rate limits work, how to interpret response headers, and best practices for handling throttling in your integration.

Overview

EliteCircle's API uses rate limiting to ensure fair usage, maintain platform stability, and protect infrastructure. Limits are enforced per API key and vary based on your subscription tier. All rate limits use a sliding window algorithm to smoothly distribute requests over time.

ℹ️

Rate limits are calculated per unique API key. If you manage multiple integrations, consider using separate keys to isolate quotas.

Tier-Based Limits

Your rate limit depends on your active plan. Enterprise customers can request custom limits directly from their account manager.

Plan	Requests / Minute	Requests / Day	Burst Allowance
Starter	60	5,000	None
Professional	300	50,000	Up to 2x for 5s
Enterprise	2,000+	Unlimited	Configurable

Response Headers

Every API response includes rate limit headers so your application can adapt dynamically. Check these headers to monitor quota consumption without guesswork.

HTTP Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 142
X-RateLimit-Reset: 1718492385
Retry-After: 45 (only present on 429 responses)

X-RateLimit-Limit: Maximum requests allowed per window.
X-RateLimit-Remaining: Requests left before hitting the limit.
X-RateLimit-Reset: Unix timestamp when the window resets.
Retry-After: Seconds to wait before making another request (only on 429s).

Handling 429 Too Many Requests

When you exceed your rate limit, the API returns a 429 status code. Your client should pause requests until the window resets or the Retry-After duration passes.

JSON Response

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 42 seconds.",
    "code": 429,
    "retry_after": 42
  }
}

⚠️

Repeatedly hammering the API after a 429 response may trigger temporary IP-level restrictions. Always respect Retry-After and implement exponential backoff.

Best Practices

Implement exponential backoff: Start with a short delay (e.g., 500ms), doubling it with each retry up to a maximum (e.g., 30s).
Cache responses: Reduce redundant calls by caching static or semi-static data locally.
Use webhooks: Instead of polling, subscribe to event webhooks to react to changes in real-time.
Monitor headers proactively: Alert your team when X-RateLimit-Remaining drops below 10% of your limit.
Distribute load: If building batch processes, queue requests and stagger execution across the window.

Need Higher Limits?

Upgrade your plan or contact our Developer Relations team for custom Enterprise quotas. We typically respond within 2 business hours and can provision temporary bursts for time-sensitive integrations.