> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://you.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://you.com/docs/_mcp/server.

# Rate Limits

## Rate Limit Headers

API usage is subject to rate limits based on your subscription tier. Every response includes three headers that describe your current limit:

* `X-RateLimit-Limit` — total requests allowed in the window
* `X-RateLimit-Remaining` — requests remaining in the current window
* `X-RateLimit-Reset` — Unix timestamp when the window resets

Read these headers to throttle client-side before you hit the limit, rather than waiting for a `429`.

## The 429 Response

When you exceed the limit, the API returns `429 Too Many Requests`. Honor the `Retry-After` header when present — it tells you exactly how long to wait before the next request.

## Exponential Backoff

For retries, use exponential backoff with a cap so a sustained burst does not lock you out for a long time. This example retries up to five times, doubling the wait between attempts up to a 60-second ceiling:

```python
import os
import time
from youdotcom import You, errors

def exponential_backoff(attempt):
    return min(2 ** attempt, 60)  # Max 60 seconds

with You(api_key_auth=os.environ["YDC_API_KEY"]) as you:
    for attempt in range(5):
        try:
            response = you.search.unified(query="test")
            break
        except errors.YouError as e:
            if e.status_code == 429 and attempt < 4:
                wait_time = exponential_backoff(attempt)
                time.sleep(wait_time)
            else:
                raise
```

For higher rate limits, [upgrade your plan](https://you.com/platform) or contact [api@you.com](mailto:api@you.com).