Skip to main content
每个 Firecrawl 错误响应都采用相同的 JSON 结构。请在下表中查找 error 的值 (或 HTTP 状态码) ,以了解错误原因、处理方法,以及该请求是否可以安全重试。
本文涵盖了大多数代理和客户端会遇到的错误,但并非完整列表——如果你遇到了此处未列出的错误,请提交 issue,以便我们将其补充到文档中。

错误响应结构

所有非 2xx 响应都会返回 JSON,顶层包含 success: false 和字符串类型的 error。某些端点在可提供更多上下文信息时,还会包含其他字段 (detailscode) 。

错误

对于 429 响应,Firecrawl 会在可用时包含 Retry-After 响应标头 (单位为秒) ——重试前至少等待这么久。

代理

/agent 及其状态、执行追踪、快照和取消端点特有的错误。执行追踪和快照端点会原样转发上游错误正文,因此这两个端点返回的正文可能不包含上述 success 字段;请根据 HTTP 状态码和 error 字符串进行判断。 达到 maxCredits 上限的运行不会返回 HTTP 错误,而是会以失败任务结束。轮询状态端点会返回 status: "failed"、额度限制错误消息、无 data,以及 creditsUsed: 0,因为失败的运行不会计费。在执行追踪中,同一结果会显示为 run.finished 事件,其中 outcome: "credit_limit_reached"

执行追踪错误代码

终止事件和 error.occurred 执行追踪事件都会携带一个结构化的 error 对象,其 code 取值为以下五种之一。每个事件还会携带一个 retryable boolean,应按与上方可重试列相同的方式处理。

重试指南

可重试 列为准;不要仅凭 HTTP 状态码自行判断。以下模式使用带抖动的指数退避,并在遇到 429 时遵循 Retry-After

429 响应

429 响应是最常见的可重试错误。各套餐的限流和并发限制详见限流。如果存在 Retry-After 标头,请务必遵循其指定的等待时间,而不要立即重试。