错误码与排查

所有 ZapFetch 错误遵循统一的响应信封:

{
  "success": false,
  "error": "short_machine_readable_code",
  "message": "Human-readable explanation of what went wrong."
}

HTTP 状态码是主要信号——error 字段用来区分同一状态码下的不同失败模式。

401 — Unauthorized

{ "success": false, "error": "unauthorized", "message": "Invalid API key." }

原因: Authorization: Bearer <ZapFetch API key> 请求头缺失、格式错误,或引用的 Key 不存在 / 已被撤销。 处理:

确认 Key 是从 Dashboard → API keys 复制的 UUID 格式 ZapFetch Key (不是 Firecrawl Cloud 的 Key)。
去 Dashboard → API keys 看 Key 是否被撤销。
确保请求打到 api.zapfetch.com,不是老的域名。

{
  "success": false,
  "error": "insufficient_credits",
  "message": "Your credit balance is 0. Upgrade or top up."
}

原因: 当月套餐 credits 用完了。 处理: 在 Billing 页面充值或升级套餐。进行中的 crawl 会跑完已派发的页面,但新请求会被拦住直到额度补上。

{ "success": false, "error": "not_found", "message": "Crawl job abc123 not found." }

原因: 资源(比如 crawl job)在你的账号下不存在,或已被回收 (crawl 结果保留 30 天)。 处理: 核对 id 和所有者;如果结果过期了就重跑一次 crawl。

完整处理方式见限流。请始终遵从 Retry-After 响应头。

{ "success": false, "error": "internal_error", "message": "Unexpected failure. Please retry." }

原因: ZapFetch 自身问题,或抓取目标页面时的瞬时上游失败。 处理: