よくある問題
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"
}'
注意: browser endpointはコンテンツをbodyフィールド(dataではなく)で返します。
403 Forbiddenまたは検証ページ
症状: APIが検証ページまたはアクセス拒否ページを含むHTMLを返します。
原因: 対象サイトがリクエストを自動化されたものとして検知し、ブロックしました。
解決策: 自動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 ローテーションの試行回数を増やしてください。
ターゲットが返した 403 は、body 内に status: 403 を含む HTTP 200 として到達します。X-FourA-Limit ヘッダーを伴うコール自体の 403 は別の問題です。プランに含まれていない 403 を参照してください。
タイムアウトエラー
症状: リクエストがタイムアウトエラーで失敗します。
原因: ターゲットページの読み込みに、設定されたタイムアウト以上の時間がかかっています。
解決策: timeout_ms を増やしてください (デフォルトは single で 15秒、browser で 30秒、proxy で 45秒):
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
}'
ブラウザリクエストの場合、checkText の値が実際にページ上に表示されていることも確認してください。タイポがあると checkText:<your text> not found で呼び出しが失敗します。
403 ご利用のプランに含まれていません
症状: APIが X-FourA-Limit ヘッダー、および plan_limit_feature または plan_limit_premium の reason とともに 403 を返します。
{
"error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
原因: ご利用中のプランには、呼び出した endpoint または送信したパラメータが含まれていません。plan_limit_feature は対象外の endpoint を示し、exitCountries、exitState、exitCity、exitAsn、または exitOs は地域ターゲティングなしのプランに適用されます。plan_limit_premium はプレミアム出口なしの exitClass: premium、およびプレミアムトラフィックを使い果たした後に exit location を指定した Proxy request を示します。ターゲットへの接続は行われず、クレジット等も消費されていません。
解決策: パラメータを削除するか、プランに含まれる endpoint を呼び出すか、アップグレードしてください。Usage & Limits の Limits & Features タブにプランに含まれる内容が一覧表示されています。変更を加えずに再試行しないでください。待機しても結果は変わらないため、Retry-After は設定されません。
429 リクエスト過多
症状: API が 429 を返します。
原因: 2つのチェックのいずれかによって呼び出しが拒否されました。どちらであるかはレスポンスで判別できます。X-FourA-Limit header が含まれている場合、該当 endpoint での同時リクエスト数や1分あたりのリクエスト数、1日の Browser リクエスト数、または請求期間のクレジットや帯域幅など、プランの上限のいずれかに達しています。該当 header がない場合は、そのサービスに対するプラットフォーム共有の1分あたりの割り当てが上限に達しており、これはユーザー自身ではなく FourA のトラフィックに起因します。
解決策: まず X-FourA-Limit を確認してください。制限解除まで数秒であれば待機し、そうでなければリクエストを停止します。待機によって解除されるプランの上限については、Retry-After header および retry_after_seconds に待機秒数が示されます。プラットフォーム共有の上限の場合は retryAfter に示されます。
import time
import requests
# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}
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:
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 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"}
)
ヘッダーにplan_limit_concurrencyまたはplan_limit_rateと示されている場合、対処法はリトライを繰り返すことではなく、開いたままにする接続数と1分あたりに開始する呼び出し数を制限することです。拒否されたバッチをすぐに再送信すると、バッチ全体が再度拒否されます。拒否された呼び出しは1分あたりの制限にはカウントされませんが、その制限の2倍以上のペースで送信され続けると、拒否状態からクールダウンに移行します。429の本文にcooldown: trueが含まれ、30秒間の一時停止(retry_after_seconds: 30)が要求されます。具体的なパターンはリクエストを並行して実行に記載されており、ダッシュボードの使用状況と制限で、現在のカウンターと上限を並べて確認できます。
503 サービス利用不可
症状: APIが503ステータスを返します。
原因: これは3つのケースで発生します:
- サービスの処理能力の上限に達している。 FourAが、ユーザー固有のトラフィックだけでなく全体トラフィックを対象として、対象エンジンで同時に実行可能な最大数のリクエストをすでに処理しています。
errorフィールドにService at capacityが設定されます。通常は数秒で解消されます。 - サービスが一時的に無効化されている。 メンテナンス期間中です。
errorフィールドにService disabledが設定されます。 - 一時的にAPIキーを確認できない。
errorフィールドにAPI key check temporarily unavailableが設定され、Retry-After: 5が返されます。キー自体に問題はありません。
3つのケースすべてで、レスポンスにretryAfterフィールドが含まれます。いずれもプランの上限によるものではありません。契約プランの上限に達した場合は、503ではなく必ず403または429にX-FourA-Limitヘッダーを付けて応答します。
解決策: 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):
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
)
time.sleep(wait)
continue
return resp
raise Exception("Request not resolved after retries")
容量上限による 503 は FourA 側の混雑を示しているため、バックオフしてリトライすることが唯一の対処法です。代わりに 429 と X-FourA-Limit で拒否される場合は、クライアント側の問題です。パイプライン内の並列リクエスト数を減らしてください。
504 アップストリームのタイムアウト
症状: API が {"error": "Upstream timeout"} を含む 504 を返します。
原因: リクエストに指定された時間内に処理が完了しませんでした。ターゲットの応答遅延、コールド状態からのチャレンジ解決、または非常に大きなページが原因となります。API キー、パラメータ、プロキシの問題ではありません。
解決策: 呼び出しの制限時間を延長するか、リトライしてください。FourA は timeout_ms にわずかなマージンを加えた時間待機するため、これを増やすと待機時間が実際に延長されます。
{
"url": "https://slow-site.com/report",
"timeout_ms": 90000
}
保護されたターゲットに対する /api/auto/ では、最初のコールドコールに数十秒かかることがあります。その timeout_ms はエスカレーション全体をカバーし、最大 180000 まで指定できます。
/api/auto/ 自体がその予算を使い果たした場合でも、呼び出しは HTTP 200 を返します。ボディには time budget exhausted で始まる error が含まれ、status は通常 504 になります(それ以前の失敗した試行のステータスが残ることもあります)。timeout_ms の値を引き上げるか、再試行してください。
502 アップストリーム利用不可
症状: API が {"error": "Upstream unavailable"} とともに 502 を返すか、{"error": "Backend service unavailable"} とともに 503 を返します。
原因: FourA が自身のエンジン(Upstream unavailable)に接続できなかったか、エンジンが利用可能な応答を返しませんでした(Backend service unavailable)。通常はインスタンスの再起動が原因です。/api/browser/ では、すべてのブラウザがビジー状態の場合、ページは空きブラウザを最大 10 秒間待機し、それでも待機が続くページはこの 503 として返されます。
解決策: 短いバックオフを挟んで再試行してください。どちらも service_error として分類され、課金されるのは success のみであるため、再試行に追加のコストは発生しません。問題が 1〜2 分以上続く場合は、ステータスページを確認してください。
401 認証エラー
症状: すべてのリクエストが 401 Unauthorized を返します。
チェックリスト:
- ヘッダーが
X-API-Key: YOUR_API_KEYであることを確認します(Authorization: BearerやApi-Keyではありません) - API キーに余分な空白や改行が含まれていないか確認します
- 現在のキーが侵害されている可能性がある場合は、ダッシュボードから新しいキーを作成します
400 無効なリクエスト
症状: POST /api/single/、/api/proxy/、または /api/browser/ の呼び出しが {"error": "Invalid request: <field>: <reason>; ..."} とともに 400 を返します。
原因: リクエストボディのフィールドが不足している、型が正しくない、または範囲外です。エラーメッセージには、受け入れられなかったフィールドとその理由が最大 5 つまで示され、それ以上ある場合は続いて and N more が表示されます。データは取得されず、結果は client_error となり、クレジットは消費されません。
解決策: 指定されたフィールドを修正してリクエストを再送信してください。同じボディでは同じ 400 が返されるため、変更せずに再試行しないでください。エンドポイントリファレンスには、各フィールドの型と制限が記載されています。/api/auto/ では、同じミスが HTTP 200 として返され、status: 400 および error に理由が含まれます。
400 ターゲットがプライベートまたは予約済みIPに解決される
症状: リクエストが FourA を離れる前に、API が Refusing to fetch <target>: target resolves to a private or reserved IP range とともに 400 を返します。
原因: url がプライベート、ループバック、または予約済み IP レンジ(RFC 5735、RFC 6598、または IPv6 予約ブロック)に解決されます。FourA のネットワークが内部ホストへのアクセスに使用されるのを防ぐため、FourA はこれらのターゲットを拒否します。
解決策: パブリック URL を取得してください。テストを行う場合は、https://example.com や https://httpbin.org/get などのパブリックターゲットを使用してください。対象のターゲットが自身で実行しているサービスである場合は、まずパブリックホスト名で公開してください。
{ "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." }
名前解決できないホスト名は拒否されません。FourAが到達できない他のターゲットと同様、呼び出しはstatus: 0と理由 (could not resolve <host>: <reason>) を含むHTTP 200として返され、課金は発生しません。
400 URL内のスペース
症状: リクエストがFourAから送信される前に、Single、Proxy、またはAutoがinvalid URL: it contains a space; encode it as %20 (the URL as sent: "...")を含む400を返します。
原因: URL内にスペースまたは制御文字が含まれています。通常、ページからそのまま取得したリンク (javascript: void(0)、テキストを含む共有リンクなど) が原因です。フェッチは実行されず、結果はclient_errorとなり、クレジットは消費されません。
解決策: 送信前にURLをエンコードし (スペースは%20)、javascript:などのページではないリンクをスキップします。BrowserはChromeと同様の方法でこのようなURLをフェッチします。
400 ターゲットがFourA API自体になっている
症状: リクエストがFourAから送信される前に、APIがRefusing to fetch <url>: that is the FourA API itself, not a page.を含む400を返します。
原因: urlがapi.foura.aiまたはeu.api.foura.aiを指しています。クローラーがページの相対リンクをページ自体のURLではなくAPIのURLに対して解決した場合に発生しやすく、/category/news/がhttps://eu.api.foura.ai/category/news/に変換されます。フェッチは実行されず、クレジットは消費されません。
解決策: 送信前に、Pythonのurljoin(page_url, href)などを使用して、すべてのリンクを取得元ページのURLに対して解決します。Inspect endpoint (/inspect) は、FourA経由でフェッチ可能なAPIホスト上の唯一のアドレスです。
exitCountries使用時のno_eligible_proxy
症状: exitCountriesを指定した/api/proxy/の呼び出しが、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プールには、ターゲットから認識される国が許可リストと一致する有効な出口が存在しません。標準プールでは、exitCountriesを設定した場合にリクエスト外の国へフォールバックすることはありません。exitCountriesがない場合、同様の状況では{"error": "Failed"}が返されます。FourAに試行可能な出口がなかったため、数秒後に再試行してください。
出口の場所を指定するリクエスト (exitState、exitCity、exitAsn、exitOs、またはexitClass: premiumを伴うexitLifetimeMin) は、プレミアム出口経由でのみ送信されます。FourAで試行可能なプレミアム出口が残っていない場合、呼び出しは"error": "No premium exit answered for this request"および同一のcode: no_eligible_proxyで終了します。
解決策: 指定したスコープを維持したまま、後で再試行してください。プールは約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")
ワークフローの国要件が実際に変更された場合にのみ、国のリストを広げてください。他国へのサイレントフォールバックは、ダウンストリームの地理依存ロジックを破壊する可能性があります。
ブラウザプロファイルが拒絶される
症状: 呼び出しが unknown profile '<id>'、no profile matches browser=...、または browser profile selection requires unblocker:true を返します。
原因: 送信した profile、browser、os、または version がカタログに存在しないか、unblocker: false と共に送信されました。
解決策: 現在のカタログについて GET /api/profiles を確認してその中から選択し、ブラウザを選択する際は unblocker を有効にしておきます。
レスポンスボディが文字化けして返される
症状: ターゲットが非 UTF-8 文字セットを使用している場合、レスポンスの data(または body)に文字化けや判読不能な文字が含まれます。
原因: デフォルトでは、FourA はターゲットの Content-Type ヘッダーまたは HTML の <meta charset> タグに基づいて、レスポンスボディを UTF-8 に自動デコードします。ターゲットが文字セットについて誤った情報を返すと、テキストが文字化けします。
解決策: バイナリペイロード(画像、protobuf、raw オーディオ)の場合、リクエストで returnBuffer: true を設定してください。Single および Proxy は、文字セット変換を適用せず、生バイトを保持するオブジェクトとして data({"type": "Buffer", "data": [<byte values>]})を返します。
{
"method": "GET",
"url": "https://example.com/image.png",
"returnBuffer": true
}
charsetの宣言が誤っているテキストターゲットの場合は、raw bytesをご自身でデコードしてください。returnBuffer: trueで取得し、data.dataのバイト値を読み取った後、正しいcharsetでデコードします。
JSONではなく予期しないHTMLが返される
症状: ターゲットサイトからJSONを期待していたが、HTMLが返された。
原因: ターゲットページがheadersに基づいて異なるコンテンツを提供している可能性があります。
解決策: Accept headerを追加し、unblockerを有効にしてリアルなブラウザheadersを送信します。
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)が目的のページではなく bot チェックになっています。
原因: ターゲットが bot チェックを実行し、FourA はそれを検出したもののクリアできませんでした。レスポンスにその旨が示されます。Single および Proxy は solved: false を含む defense を返し、Browser は defenses.present にベンダー名を含む defenseSolved: false を返します。
解決策: まず defense.vendor を確認し、その後エスカレーションしてください。Single で別のブラウザプロファイルを試すか、別のイグジットを使うために Proxy へ移行するか、JavaScript を実行するために Browser を使用します。完全なフィールドリファレンスとベンダー一覧: サイトチェック。
実際のページにのみ存在する validate.data.accept 部分文字列を追加してください。FourA が認識したチェックページは成功として扱われません。X-FourA-Check-Page ヘッダー付きで返され、課金されません。validate を設定しない場合、HTTP 200 で返される FourA が認識できないチェックページは成功とみなされ、呼び出し時ではなく後続処理で発覚することになります。
解決しない場合
上記の方法で解決しない場合:
- ステータスページ で進行中のインシデントがないか確認してください
- ダッシュボード でリクエストメトリクスを確認してください
- リクエストの詳細(失敗したレスポンスの
X-FourA-Request-Idを含む)を添えて support@foura.ai までお問い合わせください
次のステップ
- エラーハンドリング: API エラーコードリファレンス
- レート制限: 各プランおよびプラットフォームの制限とフィールド
- リクエスト結果: 結果がどのように分類されるか
- サイトチェック:
defenseフィールドが示す内容 - 適切なエンドポイントの選択: ターゲットに応じた最適なアプローチの選択
- ダッシュボードの概要: リクエストのモニタリング