> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# エラー

> すべてのAPIエラーコード、その原因、対処法、再試行すべきかどうか。

Firecrawl のエラーレスポンスは、すべて同じ JSON 形式です。原因、対処法、またリクエストを安全に再試行できるかどうかを確認するには、以下の表で `error` の値 (または HTTP ステータス) を参照してください。

<Note>この一覧では、ほとんどのエージェントやクライアントが遭遇するエラーを取り上げています。網羅的なものではありません。ここに記載されていないエラーを受け取った場合は、文書化のために [issue を作成](https://github.com/firecrawl/firecrawl/issues)してください。</Note>

<h2 id="error-response-shape">
  エラーレスポンスの形式
</h2>

2xx 以外のレスポンスはすべて、トップレベルに `success: false` と文字列の `error` を含む JSON を返します。利用可能なコンテキストが多い場合は、一部のエンドポイントで追加のフィールド (`details`、`code`) も含まれます。

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

| フィールド | 型 | 説明 |
| - | - | - |
| `success` | `boolean` | エラー時は常に `false`。 |
| `error` | `string` | 人間が読めるエラーメッセージ。以下の行を参照する際に使用します。 |
| `details` | `any` | 任意。該当する場合、フィールドごとの構造化されたバリデーションエラー。 |

<h2 id="errors">
  エラー
</h2>

| HTTP | `error` (主なメッセージ例) | 原因 | 対処方法 | リトライ可能 |
| - | - | - | - | - |
| 400 | `Bad Request` / バリデーションエラーメッセージ | リクエストボディのスキーマ検証に失敗しました (フィールドの欠落または不正) 。 | エンドポイントのリファレンスを参照し、リクエストペイロードを修正してください。該当するフィールドは `details` で確認できます。 | いいえ |
| 400 | `Invalid URL` | `url` フィールドが指定されていない、形式が不正である、またはサポートされていないスキームが使用されています。 | `http(s)://` で始まる絶対 URL を指定してください。 | いいえ |
| 400 | `THIRD_PARTY_DATA_UNSUPPORTED_URL` | このURLはサードパーティのデータプロバイダーが提供するサイトのものですが、プロバイダーが提供するのはレコード自体のページ (プロフィールページなど) のみで、その配下のサブページには対応していません。レスポンスの `code` にはこの値が設定されます。 | 配下のサブページや出品ページではなく、レコード自体のページをスクレイピングしてください。 | 不可 |
| 400 | `THIRD_PARTY_DATA_UNSUPPORTED_OPTION` | この URL(LinkedIn のプロフィールなど)はサードパーティのデータプロバイダー経由でのみ取得できますが、リクエストにプロバイダーが対応していないオプションが指定されています。対象となるのは `actions`、`profile`、`minAge`、`zeroDataRetention`、`lockdown`、`redactPII`、または `screenshot` や `branding` などの未対応のフォーマットです。`error` には該当するオプション名が示されます。レスポンスの `code` にはこの値が入ります。 | そのオプションを外してリクエストを送信してください。Team のポリシーでゼロデータ保持が必須になっている場合、これらの URL は処理できません。詳しくは [プロバイダー経由で処理される URL](/ja/features/scrape#provider-routed-urls) を参照してください。 | いいえ |
| 401 | `Unauthorized: Invalid token` | APIキーが指定されていないか、形式が正しくないか、失効しています。 | [ダッシュボード](https://www.firecrawl.dev/app/api-keys)で取得した有効なキーを使って、`Authorization: Bearer fc-...` ヘッダーを送信してください。 | 不可 |
| 402 | `Payment Required: Insufficient credits` | プランのクレジットが不足しているか、課金設定が完了していません。 | 従量課金を有効にするか、プランをアップグレードしてください。 | 不可 |
| 403 | `Forbidden` | キーにこのエンドポイントまたは機能へのアクセス権限がありません。 | 必要なスコープを持つキーを使用するか、この機能を利用できる上位プランにアップグレードしてください。 | いいえ |
| 403 | `SCRAPE_PROMPT_INJECTION_DETECTED` | `checkPromptInjection` オプションにより、スクレイピングしたページのコンテンツからプロンプトインジェクションの試みが検出されたため、スクレイピングが中止されました。 | ページのコンテンツを手動で確認してください。誤検知の場合は、`checkPromptInjection` を指定せずにリトライしてください。詳しくは[プロンプトインジェクションの検出](/ja/features/llm-extract#prompt-injection-detection)を参照してください。 | 不可 |
| 403 | `THIRD_PARTY_DATA_NOT_ENABLED` | このURLに対応するサードパーティデータプロバイダーが、組織で有効になっていません (組織の管理者が無効にした場合など) 。レスポンスの `code` にはこの値が入ります。 | 組織の管理者に依頼して、該当プロバイダーの [Alexandria](/ja/features/alexandria) ページから有効化してもらうか、エンリッチメントプロバイダーから削除してください。 | 有効化後に可能 |
| 403 | `THIRD_PARTY_DATA_ENRICHMENT_NOT_ENABLED` | URL が LinkedIn のプロフィールまたは企業ページですが、その種類のプロフィールではエンリッチメントが無効になっているか、保存済みのエンリッチメントプロバイダーのいずれもこの URL に対応していません。レスポンスの `code` にはこの値が入り、`error` にはエンリッチメント設定へのリンクが含まれます。 | 組織の管理者に依頼して、エンリッチメント設定でエンリッチメントを有効にし、プロバイダーを選択してもらってください。詳しくは[プロバイダー経由でルーティングされるURL](/ja/features/scrape#provider-routed-urls)を参照してください。 | セットアップ後 |
| 403 | `We apologize for the inconvenience but we do not support this site...` / `UNSUPPORTED_SITE` | Firecrawl はこのサイトのスクレイピングに対応しておらず、この URL を扱えるサードパーティのデータプロバイダーもありません。一部のレスポンスでは、`code` にも `UNSUPPORTED_SITE` が設定されます。 | このデータは別の取得元から取得してください。Enterpriseをご利用のお客様は、このサイトについて営業担当にお問い合わせいただけます。 | いいえ |
| 403 | `THIRD_PARTY_DATA_TERMS_REQUIRED` | リクエストを実行するには、[Alexandria](/ja/features/alexandria) のプロバイダーが定める利用規約に組織が同意する必要があります。プロバイダーは実行されていません。レスポンスの `code` にはこの値が設定され、`requiresAction.url` も含まれます。 | `requiresAction.url` を組織の管理者に共有し、管理者がそのページで規約を確認して同意してください。エージェントが独断で規約に同意してはいけません。同意後、同じリクエストを再送信してください。 | 規約への同意後 |
| 404 | `Not Found` | ジョブ ID、リソース、またはエンドポイントのパスが存在しません。 | リソース ID とエンドポイント URL を確認してください。 | 不可 |
| 404 | `THIRD_PARTY_DATA_NOT_FOUND` | このURLはサードパーティのデータプロバイダーから提供されるものですが、いずれのプロバイダーにも該当するレコードが存在しません。複数のエンリッチメントプロバイダーを利用している場合は、すべてのプロバイダーで照会済みです。レコードが見つからなかったプロバイダーの料金は発生しません。レスポンスの `code` にはこの値が返されます。 | URLが実在するプロフィールページまたは企業ページを指していることを確認してください。データ拡充プロバイダーを追加すると、対応範囲が広がる可能性があります。 | いいえ |
| 408 | `Request Timeout` | ページの読み込みが、リクエストの `timeout` で指定された時間内に完了しませんでした。 | `timeout` を延ばすか、アクションを簡素化するか、`fastMode` を使用してください。 | はい (バックオフを適用) |
| 409 | `Conflict` | リソースがオペレーションを実行できない状態にあります (例：すでに削除済み) 。 | リトライする前に状態を再取得し、整合性を確保してください。 | 不可 |
| 413 | `Payload Too Large` | リクエストボディが許容される最大サイズを超えています。 | ペイロードを小さくしてください (例：スキーマを短くする、バッチあたりのURL数を減らす) 。 | 不可 |
| 422 | `Unprocessable Entity` / 抽出スキーマエラー | スキーマが有効なJSON Schemaではないか、モデルがスキーマに準拠した結果を生成できませんでした。 | スキーマを検証する、必須フィールドを減らす、別の `model` を試す、などの対処を行ってください。 | 場合による |
| 429 | `Rate limit exceeded` | プランの1分あたりのリクエスト上限を超えています。 | リクエストを一時停止し、`Retry-After` で示された秒数だけ待ってからリトライしてください。詳しくは [Rate Limits](/ja/rate-limits) を参照してください。 | はい、バックオフが必要 |
| 429 | `Concurrency limit reached` | プランのブラウザー同時実行数の上限に達しました。 | 実行中のjobが完了するまで待つか、同時実行数を減らすか、プランをアップグレードしてください。 | 可能 (バックオフを適用) |
| 500 | `Internal Server Error` | サーバー側で未処理の障害が発生。 | 指数バックオフでリトライしてください。問題が続く場合は、request IDを添えてサポートにお問い合わせください。 | 可能 (バックオフを適用) |
| 502 | `Bad Gateway` | 上流のプロキシまたはワーカーが無効なレスポンスを返しました。 | バックオフを適用してリトライしてください。 | 可能 (バックオフを適用) |
| 503 | `Service Unavailable` | サービスが一時的にリクエストを処理できない状態です。 | バックオフを適用してリトライしてください。 | はい (バックオフを適用) |
| 504 | `Gateway Timeout` | リクエストがゲートウェイのタイムアウト時間を超えました (通常は長時間のクロールが原因です) 。 | 代わりに非同期クロール/バッチのエンドポイントを使用し、ステータスをポーリングしてください。 | 可能 (バックオフを適用) |

429 レスポンスでは、利用可能な場合、Firecrawl は `Retry-After` ヘッダー (秒単位) を含めます。リトライする前に、少なくともその時間だけ待ってください。

<h2 id="agent">
  Agent
</h2>

[`/agent`](/ja/features/agent) およびそのステータス、トレース、スナップショット、キャンセルの各エンドポイントに固有のエラーです。トレースおよびスナップショットのエンドポイントは、上流のエラーボディを変更せずに中継するため、この 2 つでは上記の `success` フィールドを含まないボディが返される場合があります。HTTP ステータスと `error` 文字列で照合してください。

| HTTP | `error` (一般的なメッセージ) | 原因 | 対処法 | リトライ可能 |
| - | - | - | - | - |
| 400 | `Invalid job ID format. Job ID must be a valid UUID.` | `jobId` パスセグメントが UUID ではありません。 | `POST /v2/agent` が返す `id` を渡してください。 | いいえ |
| 400 | `Invalid snapshot ID` | `snapshotId` パスセグメントの形式が正しくありません。 | `artifact.updated` [トレースイベント](/ja/api-reference/endpoint/agent-trace) の `snapshotId` を使用してください。 | いいえ |
| 400 | `Trace is only available for Spark 2 extracts` | このjobは、トレースを記録する Spark 2 より前に作成されています。 | このjobに対してできることはありません。新しい実行はすべて `spark-2` で実行され、トレースが記録されます。 | いいえ |
| 400 | `Snapshots are only available for Spark 2 extracts` | このjobは、スナップショットを記録する Spark 2 より前に作成されています。 | このjobに対してできることはありません。新しい実行はすべて `spark-2` で実行され、スナップショットが記録されます。 | いいえ |
| 400 | `Your team has zero data retention enabled. This is not supported on extract.` | ゼロデータ保持が強制されている Team では、Agent 実行を利用できません。 | Team でこの機能を利用できるようにするには、[support@firecrawl.com](mailto:support@firecrawl.com) までお問い合わせください。 | いいえ |
| 404 | `Agent job not found` | job ID が存在しないか、別の Team に属しています。 | job ID を確認し、実行を開始した Team のキーを使用してください。 | いいえ |
| 404 | `Snapshot not found` | このjobには、その ID のスナップショットがありません。 | トレースを再取得し、`artifact.updated` [トレースイベント](/ja/api-reference/endpoint/agent-trace) の最新の `snapshotId` を使用してください。 | いいえ |
| 409 | `Agent already finished` | すでに終端状態に達した実行に対してキャンセルが呼び出されました。 | 代わりに `GET /v2/agent/{jobId}` を poll して結果を確認してください。 | いいえ |
| 409 | `Agent is already cancelled` | すでにキャンセル処理中の実行に対してキャンセルが呼び出されました。 | `GET /v2/agent/{jobId}` を poll してください。キャンセルされた実行は、キャンセルメッセージとともに `failed` を返します。 | いいえ |
| 500 | `Failed to passthrough agent request.` | Agent サービスが送信時にjobを拒否しました。 | バックオフを使用してリトライしてください。解決しない場合は、request ID を添えてサポートにお問い合わせください。 | はい、バックオフを使用 |

`maxCredits` 上限に達した実行は HTTP エラーを返しません。失敗したjobとして完了します。ステータスエンドポイントを poll すると、`stopReason: "credit_limit_reached"` とクレジット上限に関するエラーメッセージを含む `status: "failed"`、`data` なし、`creditsUsed: 0` が返されます。失敗した実行には課金されないためです。レスポンスには、ベストエフォートで生成された `partial` が含まれる場合もあります。エラーテキストで照合するのではなく、`stopReason` を確認してください。partial を活用して実行を継続する方法については、[クレジット上限による停止の処理](/ja/features/agent#handling-credit-limit-stops) を参照してください。トレースでは、同じ結果が `outcome: "credit_limit_reached"` を持つ `run.finished` イベントとして表示されます。

<h3 id="trace-error-codes">
  トレースのエラーコード
</h3>

Terminal および `error.occurred` トレースイベントには、5種類の値のいずれかを持つ `code` を含む構造化された `error` オブジェクトが含まれます。また、各イベントには `retryable` boolean が含まれ、上記の**リトライ可能**列と同様に扱います。

| `code` | 意味と対処法 |
| - | - |
| `cancelled` | 実行をキャンセルしました。作業をやり直す場合は、新しい実行を開始してください。 |
| `credit_limit_reached` | 実行が `maxCredits` の上限に達しました。`maxCredits` を増やすか、必要な作業量が少なくなるようプロンプトを絞り込んでください。 |
| `parent_finished` | 起動元のagentが先に完了したため、サブagentが停止しました。実際の原因は、親agentのTerminalイベントで確認してください。 |
| `refused` | agentがタスクを拒否しました。プロンプトを言い換えるか、収集する権限のあるURLに対象を絞ってください。 |
| `internal` | 実行中に予期しない障害が発生しました。実行をリトライし、問題が続く場合はjob IDを添えてサポートにお問い合わせください。 |

<h2 id="retry-guidance">
  リトライのガイダンス
</h2>

**リトライ可能** 列を判断基準とし、HTTP ステータスだけで推測しないでください。以下のパターンでは、ジッター付きの指数バックオフを使用し、429 では `Retry-After` を優先します。

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```js Node theme={null}
  const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);

  async function requestWithRetry(url, init = {}, maxAttempts = 5) {
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
      const resp = await fetch(url, init);
      if (resp.ok || !RETRYABLE_STATUSES.has(resp.status)) return resp;
      // Retry-After がある場合はそれに従い、ない場合はジッター付きの指数バックオフを使用する。
      const retryAfter = resp.headers.get('Retry-After');
      const delayMs = retryAfter
        ? Number(retryAfter) * 1000
        : Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000;
      await new Promise((r) => setTimeout(r, delayMs));
    }
  }
  ```

  ```bash cURL theme={null}
  # リトライ可能なステータスに対して指数バックオフを行うシンプルなシェルループ。
  attempt=0
  max=5
  until response=$(curl -sS -w "\n%{http_code}" -X POST "https://api.firecrawl.dev/v2/scrape" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url":"https://example.com"}'); do
    status=$(printf '%s' "$response" | tail -n1)
    case "$status" in
      408|429|500|502|503|504)
        attempt=$((attempt+1))
        [ "$attempt" -ge "$max" ] && break
        sleep $((2 ** attempt))
        ;;
      *) break ;;
    esac
  done
  echo "$response"
  ```
</CodeGroup>

<h2 id="429-responses">
  429 レスポンス
</h2>

429 レスポンスは、リトライ可能なエラーで最もよく発生します。プランごとのレート制限と同時実行数の上限については、[レート制限](/ja/rate-limits) を参照してください。`Retry-After` ヘッダーがある場合は、すぐに再試行せず、必ずその指示に従ってください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.