リクエスト結果

FourA APIへのすべてのrequestは、正確に1つのoutcomeに分類されます。このoutcomeはrequest時に一度だけ計算され、お使いのAPI keyに対して記録されます。Dashboard、アクティビティフィード、および請求はすべて、この同じフィールドを参照します。

successのみが課金対象となります。

7つのoutcome

Outcome	レイヤー	意味
`success`	n/a	有効なresponseが返されました。課金対象のクォータにカウントされます。
`application_error`	target	targetはHTTP 200を返しましたが、bodyにエラーフィールドが含まれていました。
`application_fail`	target	targetが、`validate`ルールで許容されていない2xx以外のステータスを返したか、あるいはresponseをまったく返しませんでした。
`client_error`	caller	requestがFourAから送信される前に拒否されました。不正なパラメータ、不正な形式のproxy値、SSRF保護されたURLなどが原因です。
`rate_limit`	FourA	RPMまたは同時実行数の上限に達しました。
`service_error`	FourA	バックエンドが5xxを返したか、そのbodyが有効なJSONではありませんでした。
`service_fail`	FourA	ネットワークエラー：タイムアウト、接続拒否、DNSエラー、クライアントの切断。

レイヤー列は、どこに原因があるかを示しています。

target のoutcomeは、呼び出したサイトに関連するものです。お使いのrequestは問題なくFourAに到達し、FourAも問題なくtargetに到達しました。target自体がエラーを返しています。
caller のoutcomeは、request自体に問題があったことを意味します。requestの構成を修正してください。
FourA のoutcomeは、弊社側の問題です。再試行してください。問題が解決しない場合はステータスページを確認してください。

targetサイトが403を返した場合、client_errorではなくapplication_failになります。呼び出し自体は正しい形式でしたが、サイト側がアクセスを拒否したためです。

`validate`を考慮したSuccess判定

validateを使用しない場合、APIはtargetがHTTP 200を返したときにのみ、requestをsuccessと判定します。

validateを使用すると、宣言したルールに従ってsuccessが判定されます。特定の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 responseはsuccessとしてカウントされ、1回分のrequestとして課金されます。500 responseはapplication_failとしてカウントされ、課金されません。

同じロジックがvalidate.headersおよびvalidate.dataにも適用されます。エンジンが設定されたルールに照らし合わせて許容したresponseは、HTTPステータスに関わらずすべてsuccessとして返されます。

課金への影響

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

要求したデータが正常に配信されたrequestのみが課金されます。FourA側、target側、またはお客様側のいずれのエラーもすべて無料です。

Dashboardでのoutcomeの確認

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

Activityをoutcomeでフィルタリングする際、特定のプロダクト（Single、Proxy、Browser）に絞り込んで、特定のエラークラスが1つのendpointに固有のものかどうかを確認することもできます。

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

outcomeに基づいた基本的な再試行ポリシーは以下の通りです。

Outcome	再試行の安全性	条件・対応
`success`	n/a	すでにresponseを取得しています。
`application_error`	場合による	targetのエラーbodyを確認してください。一時的なものもありますが、多くは永続的なエラーです。
`application_fail`	場合による	targetからrate limit制限を受けている場合は、リクエスト速度を落としてください。ブロックされている場合は、ProxyまたはBrowserのendpointに切り替えてください。
`client_error`	いいえ	requestは同じ原因で再び失敗します。入力を修正してください。
`rate_limit`	はい	response bodyの`retryAfter`に従ってください。
`service_error`	はい	短いエクスポネンシャルバックオフ（指数関数的後退）を適用してください。
`service_fail`	はい	`service_error`と同様です。