API Error Reference | You.com | You.com

Overview of errors you might encounter

Status Code	Meaning	Action
200	Success	Request completed successfully
400	Bad Request	Check request parameters
422	Unprocessable Entity	Check for invalid parameter combinations
401	Unauthorized	Verify API key is valid
402	Payment Required	Add credits to your account
403	Forbidden	Check API key scopes/permissions
404	Not Found	Agent/resource doesn’t exist
429	Too Many Requests	Implement backoff and retry
500	Internal Server Error	Contact support if persistent

In-depth

HTTP	Code	When it happens
401	`unauthorized`	This can happen for a missing API key: `{"detail": "API key is required"}`, an invalid/expired API key: `{"detail": "Invalid or expired API key"}` or for other auth parsing errors: `{"detail": "<error message>"}`
402	`payment_required`	Your account has run out of credits: `{"detail": "Insufficient credits"}`
403	`forbidden`	API key lacks scope for the path (example: `/v1/contents`): `{"detail": "Missing required scopes"}`
404	`agent_not_found` or `agent_not_supported_yet`	The agent ID does not exist (or was deleted), or the agent uses an unsupported model/feature
422	`invalid_request`	Invalid parameter combination. For example, passing `include_domains` with `exclude_domains` or `boost_domains` in the same request: `{"error": "invalid request parameter(s)"}`
500	`Internal Server Error (auth/authorization middleware)`	This can happen in the case of authentication failure: `{"detail": "Internal authentication error"}` or authorization failure: `{"detail": "Internal authorization error"}`

Handling rate limits (429)

API usage is subject to rate limits based on your subscription tier. Rate limit details are included in response headers:

X-RateLimit-Limit - Total requests allowed
X-RateLimit-Remaining - Requests remaining
X-RateLimit-Reset - Time when limit resets (Unix timestamp)

When you exceed rate limits, you’ll receive a 429 Too Many Requests response. Honor the Retry-After header when present, and use exponential backoff for retries:

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].