リクエスト結果

FourA APIへのすべてのリクエスト、およびproxyポートを通過するすべてのトンネルは、正確に1つのoutcomeに分類されます。outcomeは呼び出しの終了時に一度だけ計算され、それを実行したクレデンシャルに対して記録されます。ダッシュボード、アクティビティフィード、請求はすべて同じフィールドを参照します。

クレジットを消費するのはsuccessのみです。プレミアムトラフィックはクレジットとは別にカウントされ、outcomeには従いません。詳細はBilling Implicationsを参照してください。

7つのOutcome

リクエストが取り得る結果は以下の7つです。トンネルではそのうち5つが使用されます。後述のTunnels Use the Same Vocabularyを参照してください。

Outcome レイヤー 意味
success 該当なし 有効なレスポンスが配信されました。請求対象のクォータにカウントされます。
application_error target ターゲットはHTTP 200を返しましたが、ボディにエラーフィールドが含まれているか、ボディがFourAの認識するボットチェックまたは拒否ページです。
application_fail target ターゲットが、validateルールで許可されていないかvalidateが送信されていない200以外のステータスを返したか、解決できないターゲットホスト名を含め、レスポンスが全くありませんでした。
client_error caller リクエストがFourAから送信される前に拒否されました。不正なパラメータ、形式が正しくないproxy値、SSRF保護されたURLなどが原因です。
rate_limit FourA 実行前にリクエストが拒否されました。プランの制限(プランに含まれないエンドポイントやパラメータに対する403、許容量の使い切りに対する429)、またはプラットフォームの共有RPMや同時実行数の制限が原因です。
service_error FourA エンジンがサーバーエラーを返したか、ボディが有効なJSONではありませんでした。
service_fail FourA FourA自体のネットワーク障害です。エンジンが時間内に応答しなかった、接続が切断された、またはユーザー側が切断しました。

レイヤー列は責任の所在を示します。

  • targetのoutcomeは、呼び出したサイトに関するものです。リクエストはFourAに正常に到達し、FourAもターゲットに正常に到達しました。ターゲット自体がエラーを返しています。
  • callerのoutcomeは、リクエストの送信自体が成立しなかったことを意味します。リクエストの形式を修正してください。
  • FourAのoutcomeは、FourA側の問題です。リトライし、解消しない場合はステータスページを確認してください。

ターゲットサイトが403を返した場合、それはapplication_failであり、client_errorではありません。呼び出しの形式は適切でした。単にサイト側が拒否しただけです。

失敗した呼び出しの形式

FourAに到達して実行された呼び出しは、その後に何が起きたとしてもHTTP 200として返されます。取得前の拒否(400、401、403、413、429)またはFourA側の障害(5xx)のみが別のHTTPステータスを使用します。したがって、outcomeはトランスポートのステータスではなく、ボディから読み取られます。

Body 発生した事象 結果
status: 200, headers, data, error なし ページが配信されました。 success
200以外の status, headers, data, error なし ターゲットが応答し、validate は送信されませんでした。その応答は data に格納されています。 application_fail
200以外の status, headers, data および error ターゲットが応答しましたが、validate ルールによって拒絶されました(例: Status 404 is not in accept list 200)。 application_fail
status: 200, headers, data および error ターゲットが HTTP 200 を返しましたが、validate ルールによって拒絶されました(例: Data not in accept list ["product"])。 application_error
error および total_time のみ、status なし、data なし ターゲットから HTTP の応答がありませんでした。リダイレクト制限への到達(Number of redirects hit maximum amount)、接続または読み取りのタイムアウト、接続のリセット、または空の応答が発生しました。テキストはエンジンの固有理由です。 application_fail
status: 0 および error のみ ホスト名を解決できません: could not resolve <host>: <reason>。エンジンは実行されず、Auto では meta もありません。DNS が更新されるまで再試行しても結果は変わりません。 application_fail

5行目のケースに該当するリダイレクトループ:

{
  "error": "Number of redirects hit maximum amount",
  "total_time": 0.808
}

POST /api/proxy/ では、試行回数を使い果たした呼び出しに error: Download maxTry limit reached と試行回数を含む attemptReport が付与されます (API Errors を参照)。POST /api/auto/ では、実行後に失敗したラダーに status、error、attempts、原因を含む attemptReport、および fail に設定された meta.rung が付与されます。

X-FourA-Credits は失敗時も含め、実行された処理を報告します。請求は success のみを対象とするため、上記の失敗したパターンのいずれも課金されません。

成功の判定は validate を認識

validate がない場合、API はターゲットが HTTP 200 を返したときのみリクエストを success としてマークします。

validate を指定した場合、成功の判定は宣言されたルールに従います。特定のリクエストに対して 200 と 403 の両方が許容可能であると API に指定した場合、403 は success として返されます。レスポンスの body は変更されずにそのまま届きます。

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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'

この呼び出しでは、403 response は success としてカウントされ、1 request として請求されます。500 response は application_fail としてカウントされ、請求されません。

同じロジックが validate.headers および validate.data にも適用されます。設定したルールに対してエンジンが受け入れた response は、HTTP status に関係なく success として返されます。

validate の有無にかかわらず、決して success にならない結果が1つあります。それは、画像認証タスクやブラウザに JavaScript の実行のみを要求するページなど、FourA が認識する bot チェックページの body を持つ HTTP 200 や、サイトが HTTP 200 で返す拒否ページです。その request は application_error となり、請求されません。body は変更されずにそのまま届き、X-FourA-Check-Page header がそのページ名を指定します。

請求への影響

Outcome 請求対象 クォータ消費
success はい はい
application_error いいえ いいえ
application_fail いいえ いいえ
client_error いいえ いいえ
rate_limit いいえ いいえ
service_error いいえ いいえ
service_fail いいえ いいえ

要求されたデータを配信した request のみが請求されます。FourA 側の障害、ターゲット側の障害、またはクライアント側の障害はすべて無料です。

この表はクレジットに関するものです。プレミアムトラフィックはクレジットとは別にカウントされます。プレミアム exit を試行した request は、exit が実際に使用されたため、結果に関係なくその試行で転送されたトラフィックがカウントされます。別の exit が応答した時点でまだ実行中だった試行は直ちに停止され、それまでに転送されたトラフィックもカウントされます。

標準トラフィックも結果に依存しません。帯域幅上限のあるプランでは、各 request のトラフィックがその上限にカウントされます。プラン自体の制限によって拒絶された request では、トラフィックはカウントされません。

トンネルでも同じ用語を使用

proxy ポート を経由するトンネルもこれらのいずれかの結果で終了するため、1組のラベルで両方の製品に対応します。ただし、2つの target の結果は FourA がターゲットの応答を確認している必要があるのに対し、トンネルの応答はクライアント自身の暗号化トラフィックであるため、発生し得るのは7つのうち5つのみです。

Outcome トンネルにおける意味
success トンネルが確立され、ツールがそれを受け取りました。
client_error FourA がそのトンネルを開きません(プライベートまたは予約済みアドレス、あるいは対応していないポート)。
rate_limit プランの上限値(同時接続トンネル数、1分あたりのトンネル開設数、対象期間の標準トラフィック、保有していないプレミアムトラフィック)に達したか、ポート自体の許容量または開設レートの上限に達しました。
service_error 要求に応じた exit が FourA に存在しませんでした。通常は一時的な状態です。
service_fail FourA が試行したどの exit を通してもターゲットに到達できませんでした(DNS、タイムアウト、接続拒否)。
application_error トンネルでは発生しません。
application_fail トンネルでは発生しません。

拒否には短い理由も付与され、ダッシュボードにはシステム内部の用語ではなくユーザー側の用語で表示されます。FourAが処理できないオプションは接続自体で400と応答され、レコードは書き込まれないため、ここには一切表示されません。

画面上の理由 不足しているリソース
port not in plan ご利用のプランに対象のproxyポートが含まれていません
tunnels at once プランで許可されている同時トンネル数がすべて使用中でした
openings per minute この1分間にプランで許可されているトンネル開設数を使い切りました
traffic used up この期間のプランのトラフィックを使い切りました
premium not available 現在ご利用のプランではプレミアムトラフィックをご利用いただけません
port was full ポート自体の容量または開設レートが上限に達していました。しばらくしてから再試行してください。
port not served FourAはそのポートへのトンネル開設に対応していません
private address プライベートアドレスおよび予約済みアドレスには到達できません

トンネルには請求対象となるrequestが存在しないため、トンネルに関してクレジットが請求されることはありません。代わりにポートがバイト数を計測します。How Your Plan Is Meteredを参照してください。

ダッシュボードでのOutcomeの確認

APIキーによって行われたすべてのrequestは、outcomeラベルとともにActivityフィードに表示されます。MetricsおよびOverviewページでは、ドーナツチャートやタイムライン用に同じフィールドが集計されます。

Activityをoutcomeでフィルタリングする際、単一のendpoint(Auto、Single、Proxy Finder、Browser)に絞り込んで、特定の障害クラスが特定のendpointに固有のものかどうかを確認することもできます。ページのProductをProxyに切り替えると、同じoutcomeピルでトンネルをフィルタリングできます。

再試行ヒューリスティクス

outcomeに基づいた一次再試行ポリシー:

Outcome 再試行可能か 条件
success 該当なし responseを受信済みです。
application_error 条件付き ターゲットのエラー本文を確認してください。一時的なものもありますが、大半はそうではありません。X-FourA-Check-Pageが設定されている場合、サイトは確認ページを返しています。URLをAutoに送信してください。Autoは確認ページを応答ではなく通過すべきステップとして処理します。
application_fail 条件付き ターゲットからrate limitを受けている場合は、速度を落としてください。ブロックされている場合は、ProxyまたはBrowser endpointに切り替えてください。
client_error 不可 requestは同じように再び失敗します。入力を修正してください。
rate_limit 条件による responseで指定された待機時間(Retry-After、retry_after_seconds、またはretryAfter)に従ってください。plan_limit_browser_dailyの場合はUTC深夜0時まで停止し、plan_limit_creditsまたはplan_limit_bandwidthの場合はresets_atまで停止し、plan_limit_featureまたはplan_limit_premiumの場合はrequestを変更してください。
service_error 可 短い指数バックオフを行ってください。
service_fail 可 service_errorと同じです。
  • API Errors: HTTPレベルのエラーレスポンス
  • Proxy Port: トンネルの拒否時に返されるステータスコード
  • Rate Limits: rate_limitのトリガー条件と、返される2種類の形式
  • Metrics: 結果の内訳を確認する場所
  • Activity Log: リクエストごとの結果履歴
最終更新日: 2026年11月11日