跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
错误响应结构

所有非 2xx 响应都会返回 JSON，顶层包含 success: false 和字符串类型的 error。某些端点在可提供更多上下文信息时，还会包含其他字段 (details、code) 。 
{
  "success": false,
  "error": "Unauthorized: Invalid token",
  "details": "Optional structured details (only present on some errors)"
}
字段类型描述
successboolean出错时始终为 false。
errorstring便于人工阅读的错误消息。可据此查找下方对应的行。
detailsany可选。适用时，包含按字段组织的结构化验证错误信息。

​
错误

HTTPerror (典型消息)原因处理方法可重试
400Bad Request / 验证消息请求体未通过 schema 验证 (字段缺失或无效) 。根据 endpoint 参考文档修正请求 payload。检查 details 中的字段。否
400Invalid URLurl 字段缺失、格式错误，或使用了不受支持的协议。传入绝对 http(s):// URL。否
401Unauthorized: Invalid tokenAPI 密钥缺失、格式错误或已被撤销。发送 Authorization: Bearer fc-...，并使用 Dashboard 中的有效密钥。否
402Payment Required: Insufficient credits套餐额度已用尽，或尚未配置计费。充值额度、启用 auto-recharge，或升级你的套餐。否
403Forbidden该密钥没有访问此 endpoint 或功能的权限。使用具备所需 scope 的密钥，或升级包含该功能的套餐。否
404Not Found任务 ID、资源或 endpoint 路径不存在。核实资源 ID 和 endpoint URL。否
408Request Timeout页面加载时间超过了请求 timeout。增加 timeout、简化 actions，或使用 fastMode。是，需退避重试
409Conflict资源当前所处状态阻止了该操作 (例如已被删除) 。重试前重新获取状态并完成协调。否
413Payload Too Large请求体超过允许的最大大小。缩减 payload (例如缩短 schema、减少每个 batch 中的 URL 数量) 。否
422Unprocessable Entity / 提取 schema 错误schema 不是有效的 JSON Schema，或模型无法生成符合要求的结果。验证 schema；放宽必填字段；尝试其他 model。有时
429Rate limit exceeded请求次数超过了你的套餐每分钟限额。退避，并在 Retry-After 指定的秒数后重试。请参见 限流。是，需退避重试
429Concurrency limit reached已达到你的套餐并发浏览器数上限。等待进行中的任务完成、降低并发，或升级你的套餐。是，需退避重试
500Internal Server Error服务端发生了未处理的故障。使用指数退避重试。如果问题持续存在，请附上请求 ID 联系支持团队。是，需退避重试
502Bad Gateway上游代理或工作进程返回了无效响应。退避后重试。是，需退避重试
503Service Unavailable服务暂时无法处理该请求。退避后重试。是，需退避重试
504Gateway Timeout请求超过了网关超时时间 (通常见于长时间爬取) 。改用异步爬取/batch 端点，并改为轮询状态。是，需退避重试
对于 429 响应，Firecrawl 会在可用时包含 Retry-After 响应头 (单位为秒) ——重试前至少等待这么久。

​
重试指南

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

RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}

def request_with_retry(method, url, headers=None, json=None, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.request(method, url, headers=headers, json=json)
        if resp.status_code < 400 or resp.status_code not in RETRYABLE_STATUSES:
            return resp
        # 存在 Retry-After 时优先遵循，否则使用带抖动的指数退避。
        retry_after = resp.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else min(2 ** attempt, 30) + random.random()
        time.sleep(delay)
    return resp

​
限流

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