よくある問題

FourA APIを使用する際のよくある問題の解決策。

空または不完全なコンテンツ

症状: APIは200ステータスを返しますが、dataフィールドが空であるか、期待されるコンテンツが欠落しています。

原因: ターゲットページが、初期ページロード後にJavaScriptを使用してコンテンツをレンダリングしています。

解決策: single endpointからbrowser endpointに切り替えます。checkTextを使用して、コンテンツが読み込まれたことを確認します:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

注: ブラウザのendpointは、コンテンツをbodyフィールドに返します（dataではありません）。

403 Forbidden または CAPTCHA ページ

症状: APIがCAPTCHAチャレンジまたはアクセス拒否ページを含むHTMLを返す。

原因: ターゲットサイトがrequestを自動化されたものとして検知し、ブロックした。

解決策: 自動IPローテーションのためにproxyのendpointを使用する:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

問題が解決しない場合は、maxTries を増やしてproxyローテーションの試行回数を増やしてください。

タイムアウトエラー

症状: requestがタイムアウトエラーで失敗する。

原因: ターゲットページの読み込みに、設定されたタイムアウトより長い時間がかかっている。

解決策: timeout_ms を増やします (デフォルトは single で15s、 browser で30s、 proxy で45s):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

ブラウザの request の場合、checkText の値が実際にページ上に存在することも確認してください。タイプミスがある場合、必ずタイムアウトが発生します。

429 Too Many Requests (RPM 制限)

症状: API が "rate limit exceeded" メッセージとともに 429 ステータスを返します。

原因: 1分あたりのリクエスト数 (RPM) 制限を超過しています。これは同時実行制限とは異なります (以下の 503 を参照してください)。

解決策: response の retryAfter フィールドを使用して適切な時間待機してから再試行してください:

import time
import requests

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

レート制限を確認するには、Dashboardで現在の使用状況を確認してください。

503 Service Unavailable

症状: APIが503ステータスを返す。

原因: 以下の2つのケースで発生します。

同時実行制限への到達。 実行中の同時リクエストが多すぎます。これは1分あたりのリクエスト数を制限する429とは異なります。503の場合、RPMは超過していませんが、同時に実行できるリクエスト数の上限に達しています。
サービスの一時的な無効化。 メンテナンス中です。

どちらのケースでも、レスポンスにretryAfterフィールドが含まれます。

解決策: retryAfter秒待機してから、再試行してください。

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

503の同時実行制限に頻繁に達する場合は、スクレイピングパイプラインの並行リクエスト数を減らすか、Dashboardでプランの同時実行制限を確認してください。

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

症状: APIは{"error": "Upstream timeout"}とともに504を返します。

原因: リクエストで宣言した時間バジェット内に処理が完了しませんでした。ターゲットの応答が遅い、コールドチャレンジの解決、または非常に大きなページなどが原因です。キー、パラメータ、またはproxyの問題ではありません。

解決策: 呼び出しにさらに時間を割り当てるか、再試行してください。FourAはtimeout_msにわずかなマージンを加えた時間を待機するため、これを増やすことで実際の待機時間が延長されます:

{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}

保護されたターゲットに対する/api/auto/の場合、コールド状態での最初の呼び出しに数十秒かかることがあります。そのtimeout_msはラダー全体をカバーし、最大180000まで受け入れます。

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

症状: APIは{"error": "Upstream unavailable"}を伴う502、または{"error": "Backend service unavailable"}を伴う503を返します。

原因: FourAは自身のエンジンに到達しましたが、通常はインスタンスが再起動中であったため、応答を使用できませんでした。

解決策: 短いバックオフで再試行してください。両方ともservice_errorとして分類され、successのみが課金されるため、再試行に追加のコストはかかりません。数分以上続く場合は、ステータスページを確認してください。

401 認証エラー

症状: すべてのrequestが401 Unauthorizedを返します。

チェックリスト:

headerがX-API-Key: YOUR_API_KEYであることを確認します(Authorization: BearerやApi-Keyではありません)。
APIキーに余分な空白や改行がないか確認します。
現在のキーが侵害されている可能性がある場合は、ダッシュボードから新しいキーを作成します。

400 ターゲットがプライベートIPまたは予約済みIPに解決される

症状: requestがFourAから送信される前に、APIはTarget <ip> resolves to a private/reserved IPを伴う400を返します。

原因: urlがプライベート、ループバック、または予約済みIP範囲(RFC 5735、RFC 6598、またはIPv6予約済みブロック)に解決されます。FourAは内部ホストへの到達にネットワークが使用されないように、これらのターゲットを拒否します。

解決策: パブリックURLを取得してください。テスト中の場合は、https://example.comやhttps://httpbin.org/getなどのパブリックターゲットを使用します。意図したターゲットが実行中のサービスである場合は、まずパブリックホスト名で公開してください。

{ "error": "Target <ip> resolves to a private/reserved IP" }

exitCountries 使用時の no_eligible_proxy

症状: /api/proxy/ 呼び出し (exitCountries を使用) が、JSON エラーエンベロープを含む HTTP 200 を返します:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

原因: 現在の proxy プールには、ターゲット側から見える国が allowlist に一致する有効な出口がありません。exitCountries を設定している場合、FourA が要求されていない国にフォールバックすることはありません。

解決策: 要求したスコープを維持したまま、後で再試行してください。プールは約10分ごとに更新されるため、現在一致しない国でも1時間以内に追加されることがよくあります。

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

ワークフローの国要件が実際に変更された場合にのみ、国のリストを拡張してください。他の国への暗黙のフォールバックは、ダウンストリームの地域依存ロジックを壊す可能性があります。

レスポンスのbodyが文字化けして返される

症状: ターゲットが非UTF-8の文字セットを使用している場合、レスポンスのdata(またはbody)に文字化けや読めない文字が含まれます。

原因: デフォルトでは、FourAはターゲットのContent-TypeヘッダーまたはHTMLの<meta charset>タグに基づいて、レスポンスのbodyをUTF-8に自動デコードします。ターゲットが文字セットを偽っている場合、文字化けが発生します。

解決策: バイナリのペイロード(画像、protobuf、rawオーディオ)の場合、リクエストでreturnBuffer: trueを設定します。bodyは文字セットの変換が適用されず、base64バッファとして返されます。

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

charsetを誤って宣言しているテキストターゲットの場合、生のバイトをご自身でデコードしてください。returnBuffer: trueでフェッチし、base64デコードした後、正しいcharsetを適用します。

JSONの代わりに予期しないHTMLが返される

症状: ターゲットサイトからJSONを期待していたが、HTMLを受け取った。

原因: ターゲットページがheaderに基づいて異なるコンテンツを提供している可能性がある。

解決策: リアルなブラウザのheaderにするため、Accept headerを追加し、unblockerを有効にする:

curl -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://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

また、tryJsonDataをtrueに設定して、FourAにJSON応答を自動的に解析させることもできます。

本文がコンテンツではなくチャレンジページである場合

症状: 呼び出しは成功し、statusは200ですが、data(またはbody)が目的のページではなくボットチェックになっています。

原因: ターゲットがボットチェックを実行し、FourAはそれに遭遇しましたがクリアできませんでした。応答はこれを示しています。SingleおよびProxyはsolved: falseでdefenseを返し、Browserはdefenses.presentのベンダーでdefenseSolved: falseを返します。

解決策: 最初にdefense.vendorを確認し、その後エスカレーションしてください。Singleで別のブラウザプロファイルを試すか、異なる出口のためにProxyに移行するか、JavaScriptが実行されるようにBrowserを使用します。完全なフィールドリファレンスとベンダーリスト: Anti-Bot Defenses。

実際のページのみが持つvalidate.data.accept部分文字列を追加します。これがない場合、HTTP 200で返されたチャレンジページが成功としてカウントされ、呼び出し時ではなく下流で気づくことになります。

まだ解決しない場合

上記の解決策のいずれも機能しない場合:

進行中のインシデントがないかステータスページを確認する
ダッシュボードでリクエストメトリクスを確認する
リクエストの詳細を記載して support@foura.ai のサポートに連絡する(失敗した応答のX-FourA-Request-Idを含める)

次のステップ

Error Handling: APIエラーコードのリファレンス
Request Outcomes: 結果が何が起こったかをどのように分類するか
Anti-Bot Defenses: defenseフィールドが示す内容
Choosing the Right Endpoint: ターゲットに最適なアプローチを選択する
Dashboard Overview: リクエストを監視する

最終更新日: 2026年8月12日