> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Warnings

> Valyu API warnings: how Search, Answer and DeepResearch report a request that succeeded with something skipped or adjusted, the warning shape and every warning type.

A warning means the request succeeded, but part of it was skipped or adjusted. An error (`4xx`) means nothing could be returned, and nothing was charged.

A plan limit never fails a request that can still return something. It succeeds, and the warning says what was left out and what unlocks it.

## Warning shape

Responses that can carry warnings have an optional `warnings` list. It is present only when there is something to say.

```json theme={null}
{
  "type": "datasets_not_in_plan",
  "message": "Your Pay-as-you-go plan doesn't include valyu/valyu-biorxiv and valyu/valyu-medrxiv (Ridiculously Cheap, $29/mo) and valyu/valyu-chemrxiv (Comfortably Pro, $99/mo), so they were skipped. Results come from your other sources. Comfortably Pro ($99/mo) includes all 3: https://platform.valyu.ai/user/account/billing?tab=plan",
  "detail": {
    "datasets": [
      {"id": "valyu/valyu-biorxiv", "required_plan": "tier_1"},
      {"id": "valyu/valyu-medrxiv", "required_plan": "tier_1"},
      {"id": "valyu/valyu-chemrxiv", "required_plan": "tier_2"}
    ],
    "current_plan": "tier_0",
    "required_plan": {"id": "tier_2", "name": "Comfortably Pro", "price": "$99/mo"},
    "upgrade_url": "https://platform.valyu.ai/user/account/billing?tab=plan"
  }
}
```

| Field | Meaning |
| - | - |
| `type` | Stable snake\_case identifier. New types may be added at any time, so handle ones you don't recognise. |
| `message` | A self-contained sentence, safe to show a user or for an agent to relay as-is. |
| `detail` | Optional, type-specific structured fields, including any URLs. |

Plan IDs map to plans as follows: `tier_0` Pay-as-you-go, `tier_1` Ridiculously Cheap (\$29/mo), `tier_2` Comfortably Pro (\$99/mo), `tier_3` Serious Business (\$499/mo). See [pricing](https://docs.valyu.ai/pricing.md).

Datasets that come from a category such as `academic` are routing candidates, not explicit requests, so skipping them never produces a warning. Only datasets you name explicitly do.

## Handling warnings

Read `warnings` after every successful response. Treat a missing list as empty, and fall back to `message` for any `type` you don't handle.

```bash cURL theme={null}
curl -s https://api.valyu.ai/v1/search \
  -H "x-api-key: $VALYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CRISPR off-target effects", "included_sources": ["valyu/valyu-pubmed", "valyu/valyu-biorxiv"]}' \
  | jq -r '.warnings[]?.message'
```

```python Python theme={null}
data = response.json()
for w in data.get("warnings") or []:
    print(w["message"])
```

```typescript TypeScript theme={null}
const data = await response.json();
for (const w of data.warnings ?? []) {
  console.log(w.message);
}
```

Branch on `type` only for the cases you act on in code, for example reading `detail.upgrade_url` from `datasets_not_in_plan` to show an upgrade button.

## For agents: relay `message` to your user

If you are an agent, pass each warning's `message` to your user unedited. It names what was skipped, what that means for the response and the one action that fixes it, with its URL. A warning is not a failure: use the results you got.

Datasets on a self-serve plan come with an `upgrade_url`. Licensed datasets and per-key limits come with a `contact_url` instead: contact us for access. To pick sources or an upgrade before searching, read `required_plan` (`{id, name, price}`, `null` when licensed separately) for each dataset from [`GET /v1/datasources`](https://docs.valyu.ai/api-reference/endpoint/datasources-list).

## Search

[`POST /v1/search`](https://docs.valyu.ai/api-reference/endpoint/search) returns these types.

| `type` | When | `detail` |
| - | - | - |
| `datasets_not_in_plan` | Datasets you named that your plan doesn't include but a self-serve plan does. The rest were searched. | `datasets[{id, required_plan}]`, `current_plan`, `required_plan{id, name, price}`, `upgrade_url` |
| `datasets_unavailable` | Datasets you named that no self-serve upgrade unlocks: licensed datasets, IDs that aren't datasets, or datasets your Enterprise plan doesn't include | `datasets[{id, reason}]` with `reason` `licensed`, `unknown` or `not_in_plan` (outside an Enterprise plan); `contact_url`, `datasources_url` |
| `datasets_deepresearch_only` | Datasets you named that are only available through DeepResearch. The rest were searched. | `datasets` |
| `max_num_results_capped` | `max_num_results` was above your key's limit, so the limit was applied | `requested`, `applied`, `contact_url` |
| `collection_not_found` | `collection:<name>` matched no collection | `collection` |
| `collection_unavailable` | A collection couldn't be resolved, so the search ran without it | `collection` |
| `source_bias_ignored` | A `source_biases` entry had no effect | `source`, `bias`, `reason` (`not_included` or `excluded`) |
| `documents_withheld` | Documents from protected datasets were withheld under their access limits | `count` |
| `source_unavailable` | A source failed while others returned results | `source` |

## Answer

[`POST /v1/answer`](https://docs.valyu.ai/api-reference/endpoint/answer) carries the warnings of the searches it ran, deduplicated, in the final `metadata` event. They use the same types as Search.

## DeepResearch

[Create task](https://docs.valyu.ai/api-reference/endpoint/deepresearch-create.md) and [Get status](https://docs.valyu.ai/api-reference/endpoint/deepresearch-status.md) return `warnings` in the same shape. A task body always has `warnings`, `[]` when there are none. DeepResearch warnings cover only problems with the request itself, never what happens during the run.

| `type` | When | `detail` |
| - | - | - |
| `datasets_not_in_plan` | Datasets you named that your plan doesn't include but a self-serve plan does | `datasets[{id, required_plan}]`, `current_plan`, `required_plan{id, name, price}`, `upgrade_url` |
| `datasets_unavailable` | Datasets you named that no self-serve plan unlocks | `datasets[{id, reason}]`, `contact_url`, `datasources_url` |
| `tool_not_granted` | A tool that needs a separately licensed grant, for example X search | `tool`, `grant`, `contact_url` |
| `tool_unavailable` | A tool the chosen mode doesn't have. The task runs without it, and `message` names the modes that have it. | `tool`, `mode`, `modes_with_tool` |
| `brand_collection_unsupported` | `brand_collection_id` isn't supported for this task | None |
| `collection_not_found` | `collection:<name>` matched no collection | `collection` |
| `collection_unavailable` | A collection couldn't be resolved, so the task runs without it | `collection` |
| `collection_empty` | The collection has no sources | `collection` |
| `sources_truncated` | `included_sources` expanded past the source limit, so only the first sources are kept | `requested`, `applied` |
| `deliverable_adjusted` | A deliverable setting, such as `slides`, was clamped or ignored | `field`, `applied` |
| `skills_unavailable` | Requested skills aren't available | `skills` |
| `batch_skills_ignored` | Skills were sent on a batch, which ignores them | None |

Older tasks may still hold plain-string warnings. Treat a string as the `message`.

## Related errors

When nothing can be returned, the request fails instead. Plan, credit and limit errors return `error` (a sentence you can relay), a stable `code` and a `recovery` object with the URLs to act on. A `429` puts its sentence in `message` instead, with `error` set to `rate_limited`. Error codes are separate from warning types: `dataset_unavailable` is an error, `datasets_unavailable` a warning. See [errors](https://docs.valyu.ai/api-reference/overview.md#errors) for every status.

| Status | `code` | When | `recovery` |
| - | - | - | - |
| `402` | `insufficient_credits` | Your balance is used up | `topup_url`, plus `upgrade_url` below the top plan |
| `402` | `credit_limit_reached` | Your monthly usage limit is reached | `increase_limit_url` |
| `402` | `spend_cap_reached` | The key's budget cap is reached | `increase_cap_url` |
| `403` | `tier_insufficient` | Every dataset you named is outside your plan | `current_plan`, `required_plan{id, name, price}` (or `null`), `required_tier`, `upgrade_url` |
| `403` | `dataset_unavailable` | Every dataset you named is licensed or unknown | `current_plan`, `contact_url`, `datasources_url` |
| `403` | `deepresearch_only` | Every dataset you named is only available through DeepResearch | `docs_url`. `restricted_sources` lists the datasets. |
| `429` | `rate_limited` | You hit your plan's [rate limit](https://docs.valyu.ai/api-reference/overview.md#rate-limits) for the endpoint | `retry_after`, `plan`, `limit`, `upgrade_url` (`contact_url` on the top plans). They also stay at the top level. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.