错误

每个 Firecrawl 错误响应都采用相同的 JSON 结构。请在下表中查找 error 的值 (或 HTTP 状态码) ，以了解错误原因、处理方法，以及该请求是否可以安全重试。

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

{  "success": false,  "error": "Unauthorized: Invalid token",  "details": "Optional structured details (only present on some errors)"}

对于 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。

import timeimport randomimport requestsRETRYABLE_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 标头，请务必遵循其指定的等待时间，而不要立即重试。