常见错误

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

鉴权说明

• 当前接口处于内测阶段
• 外部调用时，请求需要同时带 X-API-Key 和 X-Project-Id
• 在 https://browser.lexmount.cn/settings/api-keys 创建或复制 API key 与 project id
• 海外访问使用 https://browser.lexmount.com/settings/api-keys，并把接口入口替换为 https://api.lexmount.com

HTTP 状态码速查

常见错误响应

{
  "error": {
    "code": "http_status_not_ok",
    "message": "unexpected status code: 419",
    "stage": "fetch",
    "upstream_status_code": 419
  }
}

当目标站点返回了未被接受的 HTTP 状态码时，错误对象会包含 upstream_status_code；其他错误会省略这个字段。

高频错误场景

401 unauthorized

常见原因：

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

检查项：

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

400 missing project id

常见原因：

• 没有传 X-Project-Id
• API key 和 project id 不是从同一个项目复制的

检查项：

• 确认请求头名称严格为 X-Project-Id
• 确认 project id 来自同一个 API key 设置页
• 海外访问时，确认调用的是 https://api.lexmount.com

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 抓取失败

常见原因：

• 目标站点拒绝访问
• 目标站点返回了未被接受的 HTTP 状态码
• 渲染失败
• 浏览器侧抓取超时

处理建议：

• 如果响应里有 error.upstream_status_code，优先查看这个上游状态码
• 稍后重试
• 用 /v1/dom/dump 检查实际抓取结果
• 对比同站点下其他 URL 的表现

500 服务端内部错误

常见原因：

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

处理建议：

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

推荐排查流程

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