> For clean Markdown of any page, append `.md` to the page URL. > Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL). > Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key). > Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing. > OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`. # Errors ## Overview of Errors You Might Encounter 401, 403, 429, and 400 have request-level examples on [API troubleshooting](/docs/support/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](/docs/choose-the-right-api#endpoints-and-references) | | 404 | Not Found | Agent/resource doesn't exist. Check the path against the [endpoint table](/docs/choose-the-right-api#endpoints-and-references) | | 429 | Too Many Requests | Implement backoff and retry. For `spend_cap_exceeded`, raise or remove the key's spending cap | | 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": ""}` | | 402 | `payment_required` | Two distinct cases. **Out of credits** (keyed access): `{"detail": "Insufficient credits"}`—add funds at [you.com/platform](https://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](/docs/administration/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](/docs/choose-the-right-api#endpoints-and-references). | | 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)"}` | | 429 | `spend_cap_exceeded` | The API key reached its [spending cap](/docs/administration/api-keys#spending-caps). Retrying does not help. Raise or remove the cap on the [API Keys page](https://you.com/platform/api-keys). Any other `429` is a [rate limit](/docs/rate-limits). | | 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](/docs/using-the-api/rate-limits).