> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trywildcard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understanding API rate limits and how to handle them

The API defaults to **1,000 requests per hour**. Unscoped API keys under the same account share one allowance across domains and authenticated public API endpoints. Some accounts have a higher configured allowance; read `X-RateLimit-Limit` for your effective limit.

Domain-scoped keys each have their own separate 1,000-request hourly allowance. Filtering a request by domain does not give an unscoped key a separate allowance. Windows reset at the start of each UTC hour, and rejected requests also increment the counter.

## Response headers

Every response includes rate limit information:

| Header | Description | Example |
| - | - | - |
| `X-RateLimit-Limit` | Maximum requests per hour | `1000` |
| `X-RateLimit-Remaining` | Requests remaining this hour | `847` |
| `Retry-After` | Seconds until limit resets (429 only) | `1823` |

## When you hit the limit

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 1000 requests/hour.",
    "status": 429
  }
}
```

The `Retry-After` header tells you how many seconds to wait before retrying.

A 429 is an unsuccessful request, not an empty result set. Keep previously loaded visitors visible, show a temporary refresh error, and retry after the specified delay. Do not replace cached visitor data with an empty list on an API error.

## Best practices

* **Implement exponential backoff** — when you receive a 429, wait the `Retry-After` duration before retrying
* **Cache responses** — if you're making the same request frequently, cache the result
* **Use pagination efficiently** — fetch larger pages (up to 100 items) to reduce total requests
* **Sync incrementally** — use the `?since` parameter to only fetch new data since your last sync

## Example: handling rate limits in Python

```python theme={null}
import time
import requests

def api_request(url, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers={"X-API-Key": api_key})

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response.json()

    raise Exception("Max retries exceeded")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.