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.

The 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 -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, not a truncated copy. 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 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. If the workload is production volume that will stay above the default cap, raise the limit through Billing or [email protected].

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
• Answer
• Contents
• Research
• 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 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 and open Logs for recent requests, error messages, and response details. Usage totals also appear under analytics. Logs are the faster path when a single call failed.

When you contact support, include:

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

Related