リクエスト結果

FourA APIへのすべてのrequestは正確に1つのoutcomeに分類され、proxyポートを経由する各トンネルも同様です。outcomeは呼び出しの終了時に1回計算され、実行したcredentialに対して記録されます。ダッシュボード、アクティビティフィード、請求はすべて同じフィールドを参照します。

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

7つのOutcome

requestが到達する可能性のある7つのoutcomeは以下のとおりです。トンネルではそのうち5つを使用します。詳細は後述のTunnels Use the Same Vocabularyを参照してください。

Outcome	レイヤー	意味
`success`	該当なし	有効なresponseが配信されました。請求対象のクォータにカウントされます。
`application_error`	target	ターゲットはHTTP 200を返しましたが、bodyにエラーフィールドが含まれているか、FourAが認識するBotチェックページでした。
`application_fail`	target	ターゲットが`validate`ルールで許可されていない2xx以外のステータスを返したか、解決できないターゲットホスト名を含め、responseがまったくありませんでした。
`client_error`	caller	requestがFourAから送信される前に拒否されました。不正なパラメータ、無効なproxy値、SSRF保護されたURLなどが原因です。
`rate_limit`	FourA	実行前にrequestが拒否されました。プランの制限（プランに含まれないendpointやパラメータに対する403、許容量超過による429）、またはプラットフォーム共通のRPMや同時実行数の制限が原因です。
`service_error`	FourA	エンジンがサーバーエラーを返したか、bodyが有効なJSONではありませんでした。
`service_fail`	FourA	FourA自体のネットワークで障害が発生しました。エンジンの応答タイムアウト、接続切断、または呼び出し元からの切断が原因です。

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

target outcomeは呼び出し先サイトに起因します。requestはFourAに正常に到達し、FourAもターゲットに正常に到達しました。ターゲット自体がエラーを返しました。
caller outcomeは、requestが処理を開始できなかったことを意味します。requestの形式を修正してください。
FourA outcomeはFourA側に起因します。リトライを実行し、問題が解決しない場合はステータスページを確認してください。

ターゲットサイトが403を返した場合、client_errorではなくapplication_failとなります。呼び出し自体は正常でしたが、サイト側が拒否しました。

Successは`validate`を認識

validateが指定されていない場合、APIはターゲットがHTTP 200を返したときのみrequestをsuccessとマークします。

validateを指定した場合、成功判定は宣言されたルールに従います。特定のrequestに対して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 レスポンスは success としてカウントされ、1 リクエストとして請求されます。500 レスポンスは application_fail としてカウントされ、請求されません。

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

validate の有無にかかわらず、決して success にならない結果が 1 つあります。それは、視覚的な検証タスクやブラウザに JavaScript の実行のみを要求するページなど、FourA が認識する bot チェックページのボディを持つ HTTP 200 です。そのリクエストは application_error となり、請求されません。ボディは変更されずにそのまま届き、X-FourA-Check-Page ヘッダーにチェックページの名前が記載されます。

請求への影響

Outcome	請求対象	クォータへのカウント
`success`	はい	はい
`application_error`	いいえ	いいえ
`application_fail`	いいえ	いいえ
`client_error`	いいえ	いいえ
`rate_limit`	いいえ	いいえ
`service_error`	いいえ	いいえ
`service_fail`	いいえ	いいえ

要求したデータを配信したリクエストのみが請求されます。FourA 側、ターゲット側、またはユーザー側のエラーはすべて無料です。

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

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

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

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

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

拒否には短い理由も付与され、ダッシュボードには当社側の内部用語ではなく、お客様向けの分かりやすい表現で表示されます。FourAが処理できないオプションは、接続自体で400が返され、レコードは書き込まれないため、ここには一切表示されません。

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

トンネルには請求対象となるrequestが存在しないため、クレジット請求は発生しません。代わりにポート単位でバイト数が計測されます。詳細はプランの従量課金ルールを参照してください。

ダッシュボードで結果を確認する

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

Activityを結果別にフィルタリングする際、単一のエンドポイント (Auto、Single、Proxy Finder、Browser) に絞り込んで、特定の障害タイプが特定のエンドポイントに依存しているかを確認することも可能です。ページの Product をProxyに切り替えると、同じ結果ピルでトンネルをフィルタリングできます。

リトライヒューリスティクス

結果に基づいた一次リトライポリシー:

結果	安全にリトライ可能か	タイミング
`success`	該当なし	すでにresponseを取得しています。
`application_error`	条件付き	ターゲットのエラーbodyを確認してください。一部は一時的ですが、多くはそうではありません。`X-FourA-Check-Page`が設定されている場合、サイト側が検証ページを返しています。URLをAutoに送信してください。Autoは検証ページを最終結果ではなく通過すべきステップとして処理します。
`application_fail`	条件付き	ターゲットがレート制限を行っている場合は、送信ペースを落としてください。ブロックされている場合は、ProxyまたはBrowserエンドポイントに切り替えてください。
`client_error`	不可	同じ方法ではリクエストが再度失敗します。入力を修正してください。
`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`と同様。