# エラー

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

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

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

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

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

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

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

<div id="errors">
  ## エラー
</div>

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

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

<div id="agent">
  ## Agent
</div>

[`/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`                                 | このジョブは、トレースを記録する Spark 2 より前に作成されています。     | このジョブに対してできることはありません。新しい実行はすべて `spark-2` で実行され、トレースが記録されます。                                               | いいえ         |
| 400  | `Snapshots are only available for Spark 2 extracts`                            | このジョブは、スナップショットを記録する Spark 2 より前に作成されています。 | このジョブに対してできることはありません。新しい実行はすべて `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`                                                           | このジョブには、その 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 サービスが送信時にジョブを拒否しました。                 | バックオフを使用してリトライしてください。解決しない場合は、request ID を添えてサポートにお問い合わせください。                                               | はい、バックオフを使用 |

`maxCredits` 上限に達した実行は HTTP エラーを返しません。失敗したジョブとして完了します。ステータスエンドポイントを poll すると、クレジット上限に関するエラーメッセージを含む `status: "failed"`、`data` なし、`creditsUsed: 0` が返されます。失敗した実行には課金されないためです。トレースでは、同じ結果が `outcome: "credit_limit_reached"` を持つ `run.finished` イベントとして表示されます。

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

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を添えてサポートにお問い合わせください。               |

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

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

<CodeGroup>
  ```python Python
  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
  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
  # リトライ可能なステータスに対して指数バックオフを行うシンプルなシェルループ。
  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>

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

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