常见错误

这一页汇总了接入 WebFetch 时最常见的 HTTP 层和 API 层错误。

鉴权说明

• 当前接口处于内测阶段
• 外部调用时，请求需要带 X-API-Key
• 请联系管理员获取 API key

HTTP 状态码速查

常见错误响应

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid X-API-Key",
    "stage": "auth"
  }
}

高频错误场景

401 unauthorized

常见原因：

• 没有传 X-API-Key
• key 不正确，或者当前测试 key 已失效

检查项：

• 确认请求头名称严格为 X-API-Key
• 确认 key 值正确
• 确认调用的是公开服务地址

400 invalid_request

常见原因：

• JSON 格式不合法
• 缺少必填字段
• /v1/extract 的请求体结构写错

检查项：

• /v1/extract 必须传 extract 对象
• extract.url 和 extract.dom_id 至少要有一个
• /v1/dom/dump 需要顶层 url

422 模板或校验失败

常见原因：

• 没有匹配到可用模板
• 提取结果未通过校验
• 当前页面内容不适合当前路由或抓取结果

处理建议：

• 对同一 URL 重试，并在 /v1/extract 打开 trace 字段
• 调用 /v1/dom/dump 检查实际抓到的 HTML
• 确认目标页面可公开访问，且确实包含有效内容

502 抓取失败

常见原因：

• 目标站点拒绝访问
• 渲染失败
• 浏览器侧抓取超时

处理建议：

• 稍后重试
• 用 /v1/dom/dump 检查实际抓取结果
• 对比同站点下其他 URL 的表现

500 服务端内部错误

常见原因：

• 服务端出现了非预期错误

处理建议：

• 保留完整请求体
• 记录完整错误响应
• 把失败 URL 和响应内容一起反馈给管理员

推荐排查流程

1. 先用 POST /v1/extract，并保持 trace.include_steps=false
2. 如果失败，先看 HTTP 状态码和 error 对象
3. 必要时再开启 trace.include_steps=true 重试
4. 如果怀疑是页面内容本身的问题，再调用 POST /v1/dom/dump
5. 使用返回的 dom_id 再次发起提取请求，确认是否为抓取阶段问题