エラー

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

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

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

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

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

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

Terminal および error.occurred トレースイベントには、5種類の値のいずれかを持つ code を含む構造化された error オブジェクトが含まれます。また、各イベントには 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 ヘッダーがある場合は、すぐに再試行せず、必ずその指示に従ってください。