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

# API Troubleshooting

## Overview

Most failed calls to the Web Search API, Answer API, Contents API, Research API, and Finance Research API are one of four HTTP statuses. Match the status, fix the request, then use Platform Logs if you still cannot tell what the server saw.

| Status  | Typical cause                                        | First check                                                      |
| ------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
| **401** | Missing or invalid API key, or the wrong header name | [`X-API-Key`](/docs/using-the-api/authentication)                |
| **403** | Key is valid but lacks scope for that path           | [API Keys](/docs/administration/api-keys)                        |
| **429** | Too many requests in the window                      | [Rate Limits](/docs/rate-limits)                                 |
| **400** | Parameter the endpoint does not accept               | [Error code reference](/docs/using-the-api/error-code-reference) |

The [error code reference](/docs/using-the-api/error-code-reference) lists the JSON bodies for these statuses, plus 402, 404, 422, and 500.

## 401 Unauthorized

The key is missing, expired, revoked, or sent in the wrong header. You.com authenticates with `X-API-Key`, not `Authorization: Bearer`.

```curl
curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "global birth rate trends"}'
```

Confirm `YDC_API_KEY` is set in the environment that makes the request, and that the value is a key from [you.com/platform/api-keys](https://you.com/platform/api-keys), not a truncated copy. [Authentication](/docs/using-the-api/authentication) documents the header and the environment variable.

Bodies you may see: `{"detail": "API key is required"}` or `{"detail": "Invalid or expired API key"}`.

## 403 Missing Required Scopes

The key was accepted and then rejected for that path. Keys are scoped per product. A Web Search-only key calling `POST /v1/contents`, `POST /v1/answer`, `POST /v1/research`, or `POST /v1/finance_research` returns `{"detail": "Missing required scopes"}`.

Create a key that includes the product you are calling, from the [API Keys](/docs/administration/api-keys) page. Replacing the header will not help until the new key has the scope.

## 429 Too Many Requests

You exceeded the per-second limit for that endpoint. Slow the client down: lower concurrency, honor `Retry-After` when it is present, and read the `X-RateLimit-*` headers so you throttle before the next 429.

Defaults and backoff are on [Rate Limits](/docs/rate-limits). If the workload is production volume that will stay above the default cap, raise the limit through [Billing](/docs/administration/billing) or [api@you.com](mailto:api@you.com).

## 400 Bad Request

A parameter is missing, mistyped, or not valid for that endpoint. Compare the body to the OpenAPI description for the API you called:

* [Web Search](/docs/api-reference/search/v1-search)
* [Answer](/docs/api-reference/answer/v1-answer)
* [Contents](/docs/api-reference/contents)
* [Research](/docs/api-reference/research/v1-research)
* [Finance Research](/docs/api-reference/finance-research/v1-finance_research)

Some invalid combinations return **422** instead of 400, for example passing `include_domains` together with `exclude_domains` or `boost_domains` on Web Search. The [error code reference](/docs/using-the-api/error-code-reference) shows those bodies.

These endpoints do not take a `model` parameter. If a client library is sending `model`, remove it and send the fields in that API's spec.

## Debug With Platform Logs

Sign in to the [Platform](https://you.com/platform) and open **Logs** for recent requests, error messages, and response details. Usage totals also appear under [analytics](https://you.com/platform/analytics). Logs are the faster path when a single call failed.

When you [contact support](/docs/support/get-help), include:

* Request ID from Logs
* Endpoint and HTTP method
* Timestamp (UTC)
* The status and response body
* What you expected

## Related

#### [Authentication](/docs/using-the-api/authentication)

X-API-Key, YDC\_API\_KEY, and per-product scopes.

#### [Error code reference](/docs/using-the-api/error-code-reference)

Status codes and response bodies, including 402 and 422.

#### [Rate Limits](/docs/rate-limits)

Per-endpoint defaults, rate-limit headers, and backoff.

#### [Get Help](/docs/support/get-help)

[api@you.com](mailto:api@you.com), the support form, Discord, and status.you.com.