常见错误

鉴权说明

同时发送 X-API-Key 和 X-Project-Id，从同一个项目的 API 密钥设置 复制。COM 项目使用 https://api.lexmount.com，CN 项目使用 https://api.lexmount.cn；凭据必须与 API 区域匹配。

HTTP 状态说明

提取服务接受最多 1 MiB 的 JSON 请求体，并拒绝未知字段。超过其解码器限制可能返回 400 invalid_request，更早的网关也可能返回 413。保持请求精简，传 URL 或快照 ID，不要内嵌整页 HTML。

错误响应格式

提取服务的错误示例：

{
  "request_id": "01964d0f-6abc-7f1b-9345-abcdef123456",
  "error": {
    "code": "http_status_not_ok",
    "message": "unexpected status code: 419",
    "stage": "fetch",
    "upstream_status_code": 419
  }
}

目标状态导致失败时会包含 upstream_status_code。如果存在 error.dom_id 或 metadata.dom_id，可以用它定位和复用已抓取的页面。

网关错误不一定采用同一格式。项目不匹配可能返回 { "message": "projectID does not match consumer" }；上游故障可能返回 { "error": "setaria_upstream_failed" }。额度不足使用 error 对象：

{
  "error": {
    "code": "webfetch_quota_exhausted",
    "message": "webfetch quota exhausted",
    "reason": "WEBFETCH_COUNT_EXHAUSTED"
  }
}

先检查 HTTP 状态，再按实际格式读取 error.code、字符串 error 或 message。非 JSON 响应保留原始内容。提取服务响应携带 request_id 和 X-Request-ID；网关提前拒绝时不一定有 JSON 请求 ID。

常见情况

凭证与 Project ID

• 401：复制当前可用的 API Key，并使用该项目所属区域的入口。
• 400 缺少项目：补充 X-Project-Id。
• 403 项目不匹配：Key 与 Project ID 来自不同项目，应从同一项目设置复制两者。

额度或区域限制

遇到 403 webfetch_quota_exhausted，检查所选项目的 方案与用量。Extract 和 Dump 都消耗 Web Fetch 额度；先成功 dump 再成功 extract 会分别计次。反复重试不能解决额度耗尽。

遇到 client_ip_geo_blocked，检查服务的区域可用性与当前区域入口。它与密钥错误、额度耗尽不是同一问题。

输入无效

/v1/extract 需要 { "extract": { "url": "https://example.com" } }；/v1/dom/dump 使用顶层 url。提取也可以改传 extract.dom_id。使用公开 HTTP/HTTPS URL 和文档列出的字段；空/未知引擎名、错误 JSON 类型或已移除的 template_id 选项会产生输入错误。

模板或内容问题

为提取打开 trace.include_steps，并用 Dump DOM 检查页面。没有匹配模板本身不一定是错误：服务可以先用通用提取，并在后台排队生成模板。应检查实际错误，不要把所有 422 都理解成“没有模板”。

成功提取也可能缺少 main_text 等可选字段。确认抓取内容满足业务需要；HTTP 200 不保证正文质量。

抓取失败与超时

遇到 http_fetch_failed、browser_fetch_failed、network_policy_blocked 或 http_status_not_ok，检查 URL、跳转、目标可访问性、error.stage 和可能存在的 upstream_status_code。Web Fetch 面向公开网页；公司内网访问使用 SDK 本地代理。

可通过 文档中的选项 显式选择引擎。Dump DOM 成功时，其顶层 status_code 仍可能是目标站点错误，应检查 HTML 与最终 URL。对临时 502/503/504 采用有次数上限的指数退避。客户端超时不代表服务端没有执行或没有计次。

快照问题

invalid_dom_id 属于输入错误。提取时的 dom_snapshot_not_found 或快照存储错误可能返回 500。使用同一区域服务返回的原始 ID；快照不可用时重新抓取原 URL，不要持续提交失效 ID。

推荐排查顺序

1. 检查 HTTP 状态，并保存响应体。
2. 先解决凭证、项目不匹配、额度或输入错误，再重试。
3. 提取失败时打开 trace.include_steps，仅在需要时请求 raw_dom。
4. 检查 Dump DOM 的 status_code、final_url 与 HTML，有快照 ID 时再复用。
5. 仍有问题时，向支持人员提供时间、入口、可用的请求 ID，以及脱敏后的请求/响应。移除 API Key 和保密页面内容。