Tavily 搜索常见报错怎么解：401、400、432 对照排查

Tavily 搜索报错可按状态码定位并完成重试。

截至 2026 年 11 月，Tavily 官方 JavaScript SDK 已提供免密钥的 keyless 模式，适合先验证搜索链路；同时，401、400 和 432 分别对应认证、参数和套餐额度问题。现在值得按错误类型逐项排查，是因为这三种报错看起来都像“搜索失败”，实际处理路径完全不同：重装依赖解决不了 401，改写查询也解决不了 432。

开始前：先确定失败发生在哪一层

先准备一个可运行的 Node.js 或 TypeScript 项目，并确认它能够加载 Tavily SDK。官方仓库的安装命令如下：

npm i @tavily/core

接着确认 Tavily Dashboard 中可以生成 API key。认证失败的排查入口是 Tavily 错误码帮助页；若准备注册或查看账号，从 Tavily 官网 点击 Log in 进入 Dashboard。

需要区分两种调用方式：

模式	API key	可调用能力	适合场景
正常模式	提供 tvly-... key	按账号套餐使用全部已开通能力	正式项目、持续集成、团队服务
Keyless 模式	不提供 key	search 和 extract 可用，共用速率限制	临时验证、脚本试跑、本地调试

Keyless 模式不是无限免费服务。它适合确认 SDK 安装、网络和查询逻辑是否正常，但正式运行仍应根据错误信息处理限制。

最小调用：先排除安装和环境问题

直接使用官方仓库给出的搜索示例。该示例依次完成创建客户端、发送查询和打印响应三件事：

const { tavily } = require("@tavily/core");
// Step 1. Instantiating your Tavily client
const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
// Step 2. Executing a simple search query
const response = await tvly.search("Who is Leo Messi?");
// Step 3. That's it! You've done a Tavily Search!
console.log(response);

先替换 tvly-YOUR_API_KEY，再运行项目中的执行入口。成功时，控制台应打印包含搜索结果的 response 对象；如果这里已经能返回结果，原来的故障多半不在 Tavily 搜索服务，而在上层 Agent 对响应字段的解析。

如果暂时没有 API key，可以运行官方仓库提供的 keyless 示例：

const { tavily, TavilyKeylessLimitError } = require("@tavily/core");
// No apiKey — keyless mode
const tvly = tavily();
try {
  const response = await tvly.search("Who is Leo Messi?");
  console.log(response);
} catch (err) {
  if (err instanceof TavilyKeylessLimitError) {
    // Rate-limit cap hit. Inspect structured fields to decide what to do next.
    console.log("cap:", err.capType);
    console.log("retry after:", err.retryAfter);
    console.log("bonus eligible:", err.bonusEligible);
    console.log("continuation options:", err.continuationPaths);
  } else {
    throw err;
  }
}

这一步不要直接吞掉异常。err.capType、err.retryAfter、err.bonusEligible 和 err.continuationPaths 是 SDK 提供的结构化字段，应记录到日志中判断是等待重试，还是切换到带 API key 的正常模式。

401 Unauthorized：先修认证，再查搜索参数

官方帮助页给出的真实报错是：

401 Unauthorized: missing or invalid API key

出现这条信息时，优先检查 API key，而不是重写查询。依次执行：

1. 打开 Tavily 错误码帮助页，进入 401 Unauthorized 部分。
2. 确认请求中确实包含 API key；若使用 SDK，确认客户端初始化时传入了 apiKey，且值不是示例中的 tvly-YOUR_API_KEY。
3. 登录 Tavily 官网，点击 Log in 进入 Dashboard，确认 key 是否已经过期或被撤销。
4. 如旧 key 状态异常，在 Tavily Dashboard 生成新 API key，再更新客户端配置。

SDK 也支持通过 TAVILY_API_KEY 环境变量提供 key。排查时可只检查变量是否存在和值是否为空，但不要把完整 key 打印到日志或提交到 Git 仓库。

成功标志是：搜索请求不再返回 401 Unauthorized: missing or invalid API key，控制台能输出结果对象。若改完 key 后依旧出现同一报错，应确认实际运行的进程已经重新载入环境变量，并检查是否存在多份客户端配置同时生效。

400 Bad Request：逐项校正请求参数

官方帮助页记录的真实报错为：

400 Bad Request

帮助页说明，这类错误通常来自请求参数不正确或无效，例如使用了不受支持的 topic。处理顺序如下：

1. 对照 Search API Reference 检查请求字段名称、字段类型和可选值，不要把搜索接口的参数套到 extract、crawl 或 map 接口上。

2. 删除自定义参数，先用官方仓库中的基础调用验证账号与网络：

   const { tavily } = require("@tavily/core");
   const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
   const response = await tvly.search("Who is Leo Messi?");
   console.log(response);

3. 基础调用成功后，再逐个加回 search_depth、max_results、include_answer、topic 等参数。一次只加一个，便于定位具体哪个字段触发校验。

4. 如果使用了 exactMatch，按官方仓库示例传入布尔值，并把要精确匹配的短语放在双引号内：

   const { tavily } = require("@tavily/core");
   const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
   const response = await tvly.search('"John Smith" CEO Acme Corp', {
     exactMatch: true,
   });
   console.log(response);

这里最容易误判的是“接口能通，但查询写法不被接受”。基础搜索成功而加入某个参数后变成 400，已经说明认证、网络和 SDK 安装基本正常，故障范围可以收窄到该参数。

432 Plan Limit Exceeded：套餐额度与 keyless 限制

官方帮助页给出的真实报错原文是：

This request exceeds your plan's set usage limit. Please upgrade your plan or contact support@tavily.com.

这条报错不是代码语法问题，而是当前请求超过订阅套餐的用量限制。可执行的处理方式有三种：

1. 在 Tavily Dashboard 查看当前套餐和使用量；若业务必须立即恢复，按帮助页指引升级套餐。
2. 如果只是本地验证，切换到 keyless 模式，用官方仓库给出的 TavilyKeylessLimitError 捕获逻辑记录 retryAfter，到指定时间后再试。
3. 如果额度确实需要提升但升级不合适，按报错原文联系 support@tavily.com，附上发生错误的时间和请求用途。

这里不能把 432 与 keyless 限额混为一谈：432 是套餐用量超限；keyless 模式则通过 TavilyKeylessLimitError 暴露共享速率限制，字段中包含 capType 和 retryAfter。前者需要调整套餐或等待用量恢复，后者需要按结构化字段退避。

还有一种“安全拦截”并非 HTTP 错误

Tavily 官网展示的响应中出现过：

{
  "query": "hello@company.com",
  "search_depth": "",
  "max_results": "",
  "include_answer": "",
  "error": "Query blocked, PII detected with type: EMAIL"
}

这表示请求被安全、隐私和内容校验层拦截，原因是查询中包含邮箱等 PII（Personally Identifiable Information，个人身份信息）。它与 400 不同：参数格式未必错误，而是内容触发了保护规则。

处理时从 Agent 的查询生成环节入手，删除邮箱、电话号码等无必要的身份信息，并用更抽象的问题描述实体。例如，把“查找 hello@company.com 的公开资料”改成“查找 Company 的公开资料”。如果上层应用确实需要搜索邮箱，应先确认数据使用范围，再决定是否提交；不要通过反复改写请求来绕过拦截。

怎么确认已经修好

完成修复后，同时检查三项可观察结果：

1. 控制台打印 Tavily 响应对象，不再出现 400 Bad Request、401 Unauthorized: missing or invalid API key 或套餐超限文案。
2. 若使用 keyless 模式，没有触发 TavilyKeylessLimitError；若触发，错误对象能够提供 capType 和 retryAfter 等字段。
3. 将相同查询再次交给上层 Agent，确认它能读取 Tavily 返回的来源和内容，而不是因为字段解析错误把正常响应误报为“搜索失败”。

按这个顺序排查，能避免最常见的重复劳动：401 不该反复改参数，400 不该反复生成 key，432 也不该靠重启进程解决。

官方入口与进一步核对

• Tavily Search API Reference：核对搜索参数、返回字段和请求限制。
• Tavily Extract API Reference：核对从搜索结果继续提取网页内容的调用方式。
• Tavily 官方 JavaScript SDK 仓库：查看安装命令、keyless 模式、精确匹配示例和异常处理方式。
• Tavily 错误码帮助页：查询 400、401、432 等错误的官方原因与处理建议。
• Tavily API 文档首页：继续核对 search、extract、crawl、map 和 research 的接口边界。

参考来源

• | 400 Bad Request | 400 | IsError: true
• | 401 Unauthorized | 401 | IsError: true