Overview of Errors You Might Encounter
401, 403, 429, and 400 have request-level examples on API troubleshooting, including the X-API-Key header. This table is the full status list.
| 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 | Keyed access: add credits. Keyless access: a payment challenge—retry through a payment-capable client |
| 403 | Forbidden | Check API key scopes/permissions. A Missing Authentication Token body means the path is on the wrong host—check the endpoint table |
| 404 | Not Found | Agent/resource doesn’t exist. Check the path against the endpoint table |
| 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"} |
| 403 | Missing Authentication Token | The path does not exist on that host, even when the API key is valid. For example, POST https://ydc-index.io/v1/research returns {"message": "Missing Authentication Token"} because the Answer, Research, and Finance Research APIs run only on api.you.com. Check the endpoint table. |
| 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.