For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Keyed access: add credits. Keyless access: a payment challenge—retry through a payment-capable client
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
Two distinct cases. Out of credits (keyed access): {"detail": "Insufficient credits"}—add funds at you.com/platform. Payment challenge (keyless access): on GET /v1/search, /v1/agents/search (both verbs), and POST /v1/finance_research, a payment header triggers a 402 challenge carrying PAYMENT-REQUIRED and WWW-Authenticate: Payment headers. This is a challenge rather than a failure—a payment-capable client settles the charge with its own wallet and retries the request. See Machine Payments for the full endpoint list.
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)
Rate limits, the X-RateLimit-* headers, and exponential backoff are covered in Rate Limits.
