Rate Limits

Understanding and working with API rate limits

Rate Limits

Rate limits prevent abuse and ensure fair usage for all users. This guide explains limits, headers, and best practices.

Rate Limit Tiers

Account Type	Requests/Hour	Requests/Day
Guest	60	50
Free	500	Unlimited
Basic	1,000	Unlimited
Standard	2,000	Unlimited
Pro	5,000	Unlimited
Enterprise	Custom	Custom

Response Headers

Every response includes rate limit information:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1640998800

Header	Description
X-RateLimit-Limit	Max requests allowed per hour
X-RateLimit-Remaining	Requests left in current window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limit Exceeded

{
  "success": false,
  "message": "Rate limit exceeded",
  "detail": "Too many requests. Please try again later."
}

HTTP Status: 429 Too Many Requests Header: Retry-After: 3600 (seconds)

Best Practices

1. Check Headers

response = requests.get(url, headers=headers)

remaining = int(response.headers.get("X-RateLimit-Remaining"))
if remaining < 10:
    print("Warning: Approaching rate limit!")

2. Implement Backoff

def make_request_with_backoff(url, data):
    response = requests.post(url, json=data, headers=headers)

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        return make_request_with_backoff(url, data)

    return response

3. Distribute Requests

Spread requests over time instead of bursting:

import time

for item in items:
    result = api_call(item)
    time.sleep(0.1) # 10 requests/second = 360/hour (within 500 limit)

See examples →