メインコンテンツへスキップ

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 以外のレスポンスはすべて、トップレベルに success: false と文字列の error を含む JSON を返します。利用可能なコンテキストが多い場合は、一部のエンドポイントで追加のフィールド (details、code) も含まれます。 
{
  "success": false,
  "error": "Unauthorized: Invalid token",
  "details": "Optional structured details (only present on some errors)"
}
フィールド型説明
successbooleanエラー時は常に false。
errorstring人間が読めるエラーメッセージ。以下の行を参照する際に使用します。
detailsany任意。該当する場合、フィールドごとの構造化されたバリデーションエラー。

​
エラー

HTTPerror (一般的なメッセージ)原因対処法リトライ可能
400Bad Request / バリデーションメッセージリクエスト本文がスキーマ検証に失敗しました (フィールドが不足しているか無効です) 。エンドポイントのリファレンスを参照してリクエストのペイロードを修正してください。対象のフィールドは details を確認してください。いいえ
400Invalid URLurl フィールドがない、形式が不正、または未対応のスキームを使用しています。絶対URLの http(s):// を指定してください。いいえ
401Unauthorized: Invalid tokenAPI key がない、形式が不正、または失効しています。ダッシュボード の有効なキーを使って Authorization: Bearer fc-... を送信してください。いいえ
402Payment Required: Insufficient creditsプランのクレジットを使い切っているか、課金が設定されていません。クレジットを追加するか、自動チャージを有効にするか、プランをアップグレードしてください。いいえ
403Forbiddenこのエンドポイントまたは機能に対する権限がキーにありません。必要なスコープを持つキーを使用するか、この機能が使えるプランにアップグレードしてください。いいえ
404Not Foundjob ID、リソース、またはエンドポイントのパスが存在しません。リソース ID とエンドポイントの URL を確認してください。いいえ
408Request Timeoutページの読み込みに、リクエストの timeout より長い時間がかかりました。timeout を増やす、アクションを簡略化する、または fastMode を使用してください。はい、バックオフ あり
409Conflictリソースがそのオペレーションを実行できない状態にあります (例: すでに削除済み) 。リトライする前に状態を再取得し、整合性を取ってください。いいえ
413Payload Too Largeリクエスト本文が許可されている最大サイズを超えました。ペイロードを小さくしてください (例: schema を短くする、batch ごとの URL 数を減らす) 。いいえ
422Unprocessable Entity / extraction schema errorschema が無効な JSON Schema であるか、モデルがスキーマに準拠した結果を生成できませんでした。schema を検証し、必須フィールドの条件を緩めるか、別の model を試してください。場合による
429Rate limit exceededご利用プランの1分あたりの上限を超える数のリクエストが送信されました。Retry-After 秒待ってから バックオフ してリトライしてください。レート制限 を参照してください。はい、バックオフ あり
429Concurrency limit reachedご利用プランの browser の同時実行上限に達しました。実行中の jobs の完了を待つか、concurrency を下げるか、プランをアップグレードしてください。はい、バックオフ あり
500Internal Server Errorサーバー側で未処理の障害が発生しました。指数 バックオフ でリトライしてください。解消しない場合は、request ID を添えてサポートに連絡してください。はい、バックオフ あり
502Bad Gateway上流の proxy または worker が無効なレスポンスを返しました。バックオフ してリトライしてください。はい、バックオフ あり
503Service Unavailableservice が一時的にリクエストを処理できません。バックオフ してリトライしてください。はい、バックオフ あり
504Gateway Timeoutリクエストがゲートウェイの timeout を超えました (通常は長時間のクロール) 。代わりに async の crawl/batch endpoints を使い、status を poll してください。はい、バックオフ あり
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 ヘッダーがある場合は、すぐに再試行せず、必ずその指示に従ってください。