# リクエスト結果

> URL: https://foura.ai/ja/docs/api/outcomes
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

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

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

## 7つのOutcome

リクエストが取り得る結果は以下の7つです。トンネルではそのうち5つが使用されます。後述の[Tunnels Use the Same Vocabulary](#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側の問題です。リトライし、解消しない場合は[ステータスページ](https://updates.foura.ai/status)を確認してください。

ターゲットサイトが`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行目のケースに該当するリダイレクトループ:

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

`POST /api/proxy/` では、試行回数を使い果たした呼び出しに `error: Download maxTry limit reached` と試行回数を含む `attemptReport` が付与されます ([API Errors](https://foura.ai/docs/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 は変更されずにそのまま届きます。

```bash
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`](https://foura.ai/docs/api/response-headers) header がそのページ名を指定します。

## 請求への影響

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

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

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

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

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

[proxy ポート](https://foura.ai/docs/api/proxy-port) を経由するトンネルもこれらのいずれかの結果で終了するため、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](https://foura.ai/docs/guides/plans-and-metering)を参照してください。

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

APIキーによって行われたすべてのrequestは、outcomeラベルとともに[Activity](https://foura.ai/docs/dashboard/activity-log)フィードに表示されます。[Metrics](https://foura.ai/docs/dashboard/metrics)および[Overview](https://foura.ai/docs/dashboard/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](https://foura.ai/docs/api/errors): HTTPレベルのエラーレスポンス
- [Proxy Port](https://foura.ai/docs/api/proxy-port): トンネルの拒否時に返されるステータスコード
- [Rate Limits](https://foura.ai/docs/api/rate-limits): `rate_limit`のトリガー条件と、返される2種類の形式
- [Metrics](https://foura.ai/docs/dashboard/metrics): 結果の内訳を確認する場所
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): リクエストごとの結果履歴
