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:

1
import os
2
import time
3
from youdotcom import You, errors
4
5
def exponential_backoff(attempt):
6
    return min(2 ** attempt, 60)  # Max 60 seconds
7
8
with You(api_key_auth=os.environ["YDC_API_KEY"]) as you:
9
    for attempt in range(5):
10
        try:
11
            response = you.search.unified(query="test")
12
            break
13
        except errors.YouError as e:
14
            if e.status_code == 429 and attempt < 4:
15
                wait_time = exponential_backoff(attempt)
16
                time.sleep(wait_time)
17
            else:
18
                raise

For higher rate limits, upgrade your plan or contact [email protected].