Rate Limits

Sports Stack API implements rate limiting to ensure fair usage and system stability.

Rate Limit Policy

Default Limit: 1000 requests per hour per API key
Burst Limit: Up to 100 requests per minute
Rate Limit Headers: Included in all responses

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Header Descriptions

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per hour
`X-RateLimit-Remaining`	Number of requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when rate limit resets

Handling Rate Limits

429 Too Many Requests

When you exceed the rate limit, you'll receive a 429 status code:

{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded the rate limit. Please try again later.",
  "retry_after": 3600
}

Best Practices

1. Monitor Rate Limit Headers

import requests
import time

def make_request(url, headers):
    response = requests.get(url, headers=headers)

    # Check rate limit
    remaining = int(response.headers.get('X-RateLimit-Remaining', 0))

    if remaining < 10:
        reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
        wait_time = reset_time - int(time.time())
        print(f"Rate limit low. Waiting {wait_time} seconds...")
        time.sleep(wait_time)

    return response

2. Implement Exponential Backoff

import time
import random

def make_request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        # Exponential backoff with jitter
        wait_time = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait_time)

    raise Exception("Rate limit exceeded after retries")

3. Cache Responses

Cache API responses to reduce request volume:

from functools import lru_cache
import time

@lru_cache(maxsize=100)
def get_teams(league_id, cache_time=300):
    # Cache for 5 minutes
    return requests.get(
        f"https://api.sportsstack.io/api/v1/teams?league_id={league_id}",
        headers=headers
    ).json()

4. Use Webhooks Instead of Polling

Instead of polling the API, use webhooks for real-time updates:

Set up webhooks for entity changes
Receive notifications automatically
Reduce API request volume significantly

See Webhooks Guide for details.

Rate Limit Tiers

Different API key tiers have different rate limits:

Tier	Requests/Hour	Burst Limit
Free	1,000	100/min
Pro	10,000	500/min
Enterprise	Custom	Custom

Contact support to upgrade your rate limits.

Monitoring Usage

Monitor your API usage in the dashboard:

Navigate to Settings → API Usage
View request counts and rate limit status
Set up alerts for rate limit warnings