# Rate Limits

# 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:

```json
{
  "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

```python
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

```python
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:

```python
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](../guides/webhooks-guide.md) 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:

1. Navigate to **Settings → API Usage**
2. View request counts and rate limit status
3. Set up alerts for rate limit warnings

## Related Documentation

* [Quickstart](./quickstart.md) - Get started quickly
* [Authentication](./authentication.md) - API authentication
* [Webhooks Guide](../guides/webhooks-guide.md) - Reduce API calls with webhooks