APIエラー

FourA APIからのエラーを処理する方法。

エラーレスポンス形式

APIはすべてのエラーに対してフラットなJSONオブジェクトを返します。ネストされたerrorオブジェクトはありません。障害に機械可読なコードが存在する場合、それはトップレベルのフィールドになります。プラン制限ではreason、利用可能なエグジットがないプロキシ呼び出しではcodeとなります。

{
  "error": "Invalid API key"
}

一部のエラーには、トップレベルに status、service、retryAfter、current、limits などの追加フィールドが含まれます:

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

リクエストの追跡

FourAがまったく読み取れないボディ(不正な形式のJSON、または100 KBを超えるボディ)を除き、すべてのAPI response(成功またはエラー)には、その呼び出しのUUIDを含むX-FourA-Request-Id headerが含まれます。これらはIDが割り当てられる前に拒絶されます。このIDをクライアント側でログに記録してください。特定のリクエストで何が起きたかをサポートに問い合わせる際、このIDがあれば該当リクエストを特定できます。

curl -i -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...

エラーの種類

400: 不正なリクエスト

リクエストボディに必要なフィールドがないか、無効な値が含まれているか、APIが取得を拒否するターゲットが指定されています。

JSONオブジェクトまたは配列ではないボディは不正な形式のJSONとみなされ、以下に示すInvalid JSON in request bodyが返されます。

Single、Proxy Finder、Browserでは、フィールドの欠落、不正な型、または許容範囲外の値がある場合、メッセージ内で<field>: <reason>として指定されます。ネストされたフィールドはドットで連結されます (validate.status.accept)。最大5件の問題が; で区切られてリストされ、それを超える場合はメッセージの末尾がand <n> moreとなります:

{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}

これはclient_errorであり、課金されません。Autoは受け入れられないフィールドをHTTP 200内で報告します。詳細は後述の「/api/auto/からの失敗の読み取り」を参照してください。

同じ400エラーはSSRF保護にも適用されます。urlがプライベート、ループバック、またはその他の予約済みIP範囲(RFC 5735、RFC 6598、IPv6予約ブロック)に解決される場合、リクエストはFourAのネットワークから出る前に拒否されます。

{
  "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts."
}

<target> はアドレス、またはホスト名とそれが解決されたアドレスです。パースできない URL、または http:// や https:// ではない URL にも同様に 400 が返されます。

FourA 自身の API ホスト(eu.api.foura.ai または api.foura.ai)を対象とするターゲットも、フェッチや課金が行われる前に、Single、Proxy Finder、Browser、Auto で 400 になります。これは通常、ページから取得したリンクが、ページ自体の URL ではなく API URL に対して解決されたことを意味します。

{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}

<url> は送信されたままのターゲットです。Inspect ページは唯一の例外であり、FourA は引き続き https://eu.api.foura.ai/inspect を取得します。

スペースや制御文字を含む URL も、Single、Proxy Finder、Auto において、取得や課金が行われる前に 400 を返します。ページからそのままコピーしたリンクには、これらが含まれることがよくあります(javascript: void(0)、テキスト内にスペースを含む共有リンクなど)。スペースを %20 としてエンコードしてください。Browser は Chrome と同様にそのような URL を取得します。

{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}

名前解決できないホスト名は拒否されません。呼び出しは HTTP 200 として status: 0 および理由 (could not resolve <host>: <reason>) とともに返され、課金されません。FourA が接続を試みたものの HTTP 応答が得られなかったターゲット (リダイレクト上限、接続または読み取りのタイムアウト、リセット) も、HTTP 200 として返され、error および total_time が含まれ、status は含まれません。詳細は Request Outcomes を参照してください。

Single では、デコード後のレスポンス body が 128 MB を超えるとそこで停止します。呼び出しは HTTP 200 として "error": "Response body exceeds the 128 MB limit" とともに返され、課金されません。

body 内の不正な形式の JSON は、フィールドが読み取られる前に同様に拒否されます。

{
  "error": "Invalid JSON in request body"
}

proxyフィールドとignoreProxiesフィールドには、固有の400エラーがあります。どちらも以前のレスポンスで返された不透明なproxy IDを受け取るため、それ以外の値はデコードに失敗します。

メッセージ 原因
Invalid proxy format proxyの値がFourAの発行したproxy IDではありません。未加工のproxyアドレスを指定するとこのエラーになります。
Invalid ignoreProxies format ignoreProxies内のエントリの1つがproxy IDではありません。
Proxy not found IDは正常にデコードされましたが、有効な出口に解決されなくなりました。新しいものを選択してください。
Managed exit: this proxy id cannot be pinned to a request 出口は実在しますが、FourAが指定リクエスト用に維持するものではありません。プランのプレミアムトラフィック残量がない場合、プレミアム出口のIDを指定するとこのエラーになります。返却されたセッションを再利用するか、POST /api/proxy/経由で呼び出しを実行して自動選択された出口を使用してください。

修正方法: リクエストに必要なすべてのフィールドが含まれていること、URLがhttp://またはhttps://を使用しスペースが%20としてエンコードされていること、ホストがパブリックアドレスに解決されること、proxyの値が以前のレスポンスからそのままコピーされたIDであることを確認してください。

これらはclient_errorの結果です。リクエストはFourAから送信されていないため、クレジットなどは消費されていません。

401: 認証エラー

APIキーが見つからないか、無効です。

キーが不足している場合:

{
  "error": "Missing API key. Include X-API-Key header."
}

無効なキー:

{
  "error": "Invalid API key"
}

修正方法: X-API-Key ヘッダーに有効なキーが含まれていることを確認してください。必要に応じて ダッシュボード から新しいキーを生成してください。

401 は常に、FourA がキーを検証した上で拒絶したことを意味します。FourA が一時的にキーを検証できない場合は、401 ではなく 503 API key check temporarily unavailable を返します (下記参照)。

403: プラン対象外

ご利用のプランに含まれていない endpoint またはパラメータがリクエストされました。response では X-FourA-Limit が設定され、body 内の reason にも同じコードが含まれます:

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

reasonは、プランに含まれないendpoint、またはジオターゲティングなしのプランでのexitCountriesおよびイグジットロケーションフィールドに対してはplan_limit_featureとなります。また、プレミアムイグジットなしのプランでのexitClass: premium、またはプレミアムトラフィックの残量がないexit locationに対してはplan_limit_premiumとなります。error文字列には該当するendpointまたはパラメータ名が入ります。

FourAからの403はターゲットサイトに起因するものではありません。ターゲットには一度も接続されていません。ターゲットが返した403は、本文内にstatus: 403を含んだHTTP 200として届きます。

解決策: パラメータを削除するか、プランに含まれるendpointを呼び出すか、プランをアップグレードしてください。待機しても結果は変わらないため、Retry-Afterは設定されません。コストは発生していません。結果はrate_limitであり、successのみが請求されます。

413: ペイロードが大きすぎます

JSONのrequest bodyがFourAの許容サイズ(100 KB)を超えています。本文は読み取られる前に拒否されるため、応答はJSON形式ではなく、X-FourA-Request-Idも含まれません。

解決策: より小さいdataペイロードを送信してください。コストは発生していません。

429: レート制限超過

429を返すチェックは2種類あり、それぞれ含まれるフィールドが異なります。

プラン固有の制限: 応答には呼び出しを拒否した制限を示すX-FourA-Limitヘッダーが設定され、本文のreasonにも同じコードが含まれます。

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

reasonはplan_limit_concurrency、plan_limit_rate、plan_limit_browser_daily、plan_limit_credits、またはplan_limit_bandwidthのいずれかです。待機が有効な場合、待機時間はretry_after_secondsおよびRetry-Afterヘッダーに設定され、retryAfterには設定されません。plan_limit_browser_dailyにはどちらも含まれません。利用枠は秒単位ではなくUTCの深夜0時にリセットされるためです。消費は発生していません。結果はrate_limitであり、課金対象はsuccessのみです。

プラットフォームの共有利用枠。 X-FourA-Limitヘッダーはなく、待機時間はretryAfterに含まれます:

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

currentとlimitsは、お客様のアカウントではなくトラフィック全体におけるサービス状態を示します。ここでの拒否は、FourAが高負荷状態であることを意味します。

対処法: レスポンスに含まれるRetry-After、retry_after_seconds、retryAfterのいずれかの指定時間だけ待機してください。同時実行数やレートリミットによる制限の場合は、拒否されたバッチを再送するのではなく、オープンにしておくリクエスト数を制限してください。1日または請求期間の制限の場合は、実行を停止してください。各フィールドの詳細はレートリミットを、実装パターンは並行してリクエストを実行するを参照してください。

500: サーバーエラー

サーバー側で問題が発生しました。

対処法: 少し時間をおいてからリクエストを再試行してください。エラーが解消されない場合は、ステータスページを確認するか、失敗したレスポンスのX-FourA-Request-Idを添えてサポートまでお問い合わせください。

502: アップストリーム利用不可

FourAが自社エンジンから応答を取得できなかったか(Upstream unavailable: 接続失敗)、読み取れない応答を受信しました(Malformed JSON from backend)。

{
  "error": "Upstream unavailable",
  "details": "..."
}

解決方法: 短いバックオフを挟んでリトライしてください。これはこちらの問題であるため、費用は発生しません。結果はservice_errorとなり、課金対象はsuccessのみです。

504: アップストリームのタイムアウト

このリクエストの制限時間内にエンジンが処理を完了できませんでした。

{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}

504は処理にかかった時間に関するものであり、キー、パラメータ、プロキシの問題ではありません。ターゲットの応答遅延、初回のチャレンジ解決、大きなページサイズが一般的な原因です。

解決策: requestのtimeout_msの値を引き上げるか(Singleは最大120000、Browserは最大120000、Autoは最大180000まで指定可能)、再試行してください。FourAは指定された制限時間にわずかな猶予を加えた時間だけ待機するため、時間を長く設定すれば実際に待機時間が延長されます。

503: サービス停止またはキャパシティ超過

503は、メンテナンスのためサービスが一時的に利用できないか、プラットフォームの同時実行数の上限に達していることを意味します。どちらの場合も、error、status、service、retryAfter、current、limitsの同じキーが含まれます。存在するフィールドではなく、errorの文字列で判別してください。

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

Service disabled はメンテナンスを示し、計測前にリクエストが拒否されたため、current の両方のカウンターは 0 となります。Service at capacity は同時実行数の形式であり、current にはプラットフォームの実際のリソース使用状況が保持されます。その形式については Rate Limits を参照してください。

解決方法: retryAfter 秒待機してから再試行してください。ステータスページには実施中のメンテナンス期間が記載されています。

3 つ目の 503 の形式には retryAfter が含まれません。これは、endpoint の背後にあるエンジンが呼び出しを受け取れなかったことを意味します。再起動中であったか、リクエストの実行前に FourA 側で障害が発生したか、または (Browser の場合) ページがブラウザの割り当てを待機する 10 秒間、すべてのブラウザがビジー状態のままでした。backend_status はエンジン自体のステータスコードであり、detail はそのレスポンスの先頭部分です:

{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}

これは service_error であり、課金されません。1〜2秒後に再試行してください。リクエスト自体に問題がある場合はここには到達せず、フィールド名を指定した400が返されます。

4つ目の503は、データベースのフェイルオーバー中などにより、FourA が一時的に API キーを確認できなかったことを意味します。キー自体に問題はなく、何も実行されていません。このレスポンスには Retry-After: 5 と、retryAfter に同様の待機時間が含まれます。

{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}

請求は発生しません。retryAfter 秒後に再試行してください。過去10分間に FourA が確認したキーはこのような状況でも動作し続けるため、この応答はまれです。

/api/auto/ からの失敗の読み取り

POST /api/auto/ はラダーが実行された場合、すべての段階が失敗したときでも HTTP 200 を返します。実際の結果はボディに含まれます:

{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}

status はターゲットが最後に返したステータスです。試行がターゲットに到達しなかった場合は 502 になり、時間制限が先に切れた場合は 504 になります。実行されたラダーからの失敗レスポンスにはすべて、各試行で発生した事象をカウントする attemptReport、ログ記録に適した1行の summary が含まれ、meta.attemptsByEngine および meta.browserRequests には呼び出しで送信された内容が示されます。詳細は Auto 呼び出しが失敗した理由 を参照してください。Auto が受け入れられない request フィールド(例: 5000 未満または 180000 超の timeout_ms)も同様に返されます。試行が行われる前に費用なしで、HTTP 200 とともに "status": 400 が返され、error に理由が示されます。

そのため、Auto ではトランスポートステータスで条件分岐しないでください。代わりに body から status と error を読み取ります。/api/auto/ からの正規の非 200 は、ラダーの開始前に FourA が呼び出しを拒否したか、完了できなかったことを意味します: 400(不正な形式の JSON、プライベートまたは予約済みターゲット、あるいは FourA 自身の API ホスト上のターゲット)、401、413、502、503、または 504 です。プランの制限が 1 つだけエントリー時点で返されます。プレミアム exit のないプランでの exitClass: premium は、処理が実行される前に X-FourA-Limit: plan_limit_premium を伴う 403 になります。それ以外のすべての制限(ユーザー側またはプラットフォーム側の制限)は、200 の内部の body にそのステータスを含めて返されます。

サイトで特定の API key による Auto 呼び出しが連続して複数回失敗した場合、Auto は一定期間、試行を行わずにそのキーからの以降の呼び出しに対して即座に応答します: "error": "target temporarily unservable, retry later"、"status": 503、および秒単位の retryAfter です。費用は発生しません。retryAfter 秒待機してください。

サブ呼び出しのいずれかがプラン制限に達した場合も、HTTP 200 として返されます。body は拒否内容そのものであり、reason に加えて status と meta が含まれます。また、response には直接拒否された場合と同じ X-FourA-Limit header が付与されます:

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

どの制限がラダーを停止させ、どの制限が特定の段階のみを閉じるかについては、Smart Fetch (Auto)で説明しています。

200 OK 内のターゲット側障害

すべての障害が 2xx 以外の HTTP ステータスとして現れるわけではありません。ターゲットが HTTP 200 を返しても、FourA の応答に error が含まれる場合(例えば validate ルールによってボディが拒絶された場合など)や、ボディが FourA が認識するチェックページである場合、結果は application_error になります。ターゲットが validate ルールで許可されていない 200 以外のステータスを返した場合、結果は application_fail となり、ボディは変更されずにそのまま渡されます。

どちらのケースも課金されず、success のみが課金対象です。すべてのブラウザがビジー状態である Browser 呼び出しは、空きができるまで最大 10 秒間待機します。空きが生じない場合、前述の 503 Backend service unavailable として返されます。また、Browser はブラウザをまったく取得できなかった場合に HTTP 200 と "error": "No available browser slot" を返すこともあります。どちらも課金されません。数秒後に再試行するか、同時に開く Browser 呼び出しの数を減らしてください。詳細な分類については Outcomes リファレンスで解説しています。

固定した proxy を経由する Single 呼び出しでも、ボディとともに HTTP 200 と "error": "The exit gave the same answer for <n> different sites" が返される場合があります。これは FourA が、該当の出口が無関係なサイトに対しても同じページを返していることを検知したためであり、そのページは要求したものではなく出口独自のものであることを示します。これは application_error であり、課金されません。該当の出口を自動的にスキップする POST /api/proxy/ から新しい出口を取得してください。

サイトの代わりに出口自体のネットワークが応答した場合も同様です。この呼び出しは、"error": "The exit answered instead of the site (<name>)" または "error": "Corporate web gateway intercepted the request (<name>)"(サインインページやフィルタリングページ、あるいはそれらへのリダイレクト)、出口がサイト自体の代わりに応答した場合は "error": "The exit intercepted TLS and answered instead of the site (<name>)"、出口がリクエスト自体のコピーを返送した場合は "error": "Honeypot echo proxy (plaintext request dump)" とともに返されます。FourA は validate ルールの設定に関わらずこれらをチェックし、これには returnBuffer のダウンロードも含まれます。これらはいずれも課金されません。同様に新しい出口を取得してください。

レスポンスのエンコーディング

FourA はレスポンスボディを UTF-8 に自動デコードします。ターゲットが windows-1251、gbk、shift_jis、iso-8859-*、または Content-Type ヘッダーや HTML の <meta charset> タグで宣言されたその他の文字セットを提供している場合、data(single、proxy)または body(browser)フィールドにクリーンな UTF-8 文字列が返されます。

バイナリペイロード(画像、protobuf、生の音声)の場合は、リクエストで returnBuffer: true を設定してください。Single および Proxy は、文字セットのトランスコーディングを行わずに、未加工のバイトを保持するオブジェクトとして data({"type": "Buffer", "data": [<byte values>]})を返します。

再試行戦略

実用的な再試行ポリシー:

import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")

プロキシ失敗時のレポート保持

試行回数を使い果たしたPOST /api/proxy/呼び出しは、HTTPエラーコードではなく、エラーエンベロープを含むHTTP 200として返されます。エラー文字列は短く常に同じ形式であるため、カウントを含むattemptReportオブジェクトが一緒に付与されます:

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}

エラーと併せてattemptReport.summaryを記録することで、出口がブロックされていたのか、停止していたのか、または自身の設定したvalidateルールによって拒否されたページが返されていたのかを特定できます。フィールドのリファレンスおよび各カウントへの対処方法については、プロキシリクエストのリトライ上限到達理由を参照してください。

最終更新日: 2026年11月13日