# Rate Limiting

## Overview

The Skimmer Public API enforces rate limits to ensure fair usage and maintain service reliability for all consumers. Rate limits are applied **per API key**.

## Rate Limit Thresholds

| Limit | Value |
|-------|-------|
| Requests allowed | **500 requests** |
| Time window | **1 minute** |

Each API key can make up to 500 requests per minute. The limit resets at the end of each 1-minute window.

## Rate Limit Response Headers

Every API response includes headers that indicate your current rate limit status:

| Header | Description |
|--------|-------------|
| `RateLimit-Limit` | The maximum number of requests allowed in the current time window |
| `RateLimit-Remaining` | The number of requests remaining in the current time window |
| `RateLimit-Reset` | The number of seconds until the current time window resets |

## Exceeding the Rate Limit

If you exceed the rate limit, the API will respond with:

- **HTTP Status**: `429 Too Many Requests`
- **`Retry-After` header**: The number of seconds to wait before making another request

### Example 429 Response

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 500
RateLimit-Remaining: 0
RateLimit-Reset: 30
```

## Recommended Retry Strategy

When you receive a `429` response, use **exponential backoff** to retry:

1. Wait for the duration specified in the `Retry-After` header
2. If `Retry-After` is not present, wait 1 second before the first retry
3. Double the wait time for each subsequent retry (1s, 2s, 4s, 8s, ...)
4. Set a maximum number of retries (e.g., 5) to avoid infinite loops

### Example (pseudocode)

```
maxRetries = 5
delay = retryAfterHeader ?? 1

for attempt in 1..maxRetries:
    response = makeRequest()
    if response.status != 429:
        break
    sleep(delay)
    delay = delay * 2
```

## Best Practices

- **Monitor your usage** using the `RateLimit-Remaining` header to proactively throttle requests before hitting the limit
- **Batch operations** where possible to reduce the total number of API calls
- **Cache responses** for data that does not change frequently to avoid unnecessary requests