# 请求结果

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

发往 FourA API 的每个 request 都会归类为确切的一种 outcome，通过 proxy 端口的每个 tunnel 也是如此。outcome 在调用结束时计算一次，并记录在发起调用的凭据下。您的控制台、活动源和计费都读取同一个字段。

只有 `success` 会消耗积分。Premium 流量与积分分开计算，不受 outcome 影响：参见 [计费影响](#billing-implications)。

## 七种 Outcome

以下是一个 request 可能结束的七种状态。tunnel 使用其中的五种：参见下文 [Tunnel 使用相同的词汇](#tunnels-use-the-same-vocabulary)。

| Outcome | 层级 | 含义 |
|---------|-------|--------------|
| `success` | 不适用 | 已交付有效 response。计入您的计费配额。 |
| `application_error` | target | 目标返回了 HTTP 200，但 body 包含 error 字段，或者 body 是 FourA 可识别的机器人拦截或拒绝页面。 |
| `application_fail` | target | 目标返回的状态码非 200，且您的 `validate` 规则未接受，或您未传入 `validate`，或完全没有 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 是我们侧的问题。请重试，如果持续出现，请检查 [状态页](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` |

重定向循环（如第五行所示）：

```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`，并将 `meta.rung` 设为 `fail`。

`X-FourA-Credits` 即使在失败时也会报告已执行的操作。计费仅计算 `success`，因此上述失败形态均不收费。

## 成功判定感知 `validate`

未配置 `validate` 时，API 仅在目标返回 HTTP 200 时才将 request 标记为 `success`。

配置 `validate` 后，成功判定将遵循您声明的规则。如果您告知 API 针对某个指定 request，200 和 403 均可接受，则 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 响应计为 `success` 并计费为一次请求。500 响应计为 `application_fail` 且不计费。

同样的逻辑也适用于 `validate.headers` 和 `validate.data`。只要引擎根据您的规则接受了该响应，无论 HTTP 状态如何，都会作为 `success` 返回。

无论是否带有 `validate`，有一种响应绝不会是 `success`：HTTP 200 且其 body 为 FourA 可识别的机器人检查页面，例如人机验证任务、仅要求浏览器运行 JavaScript 的页面，或目标网站通过 HTTP 200 返回的拒绝访问页面。该请求判定为 `application_error` 且不计费。Body 仍会原封不动地返回给您，并且 [`X-FourA-Check-Page`](https://foura.ai/docs/api/response-headers) header 会指明该页面类型。

## 计费影响

| Outcome | Billable | Counts toward quota |
|---------|----------|--------------------|
| `success` | Yes | Yes |
| `application_error` | No | No |
| `application_fail` | No | No |
| `client_error` | No | No |
| `rate_limit` | No | No |
| `service_error` | No | No |
| `service_fail` | No | No |

只有成功交付所需数据的请求才会计费。FourA 端、目标端或您自身端发生的失败均完全免费。

上表针对的是 credit。Premium 流量与 credit 分开计算：无论结果如何，只要请求尝试使用了 [premium 出口](https://foura.ai/docs/api/endpoints#exitclass)，就会计算该次尝试所产生的流量，因为出口均已被实际占用。当另一个出口已返回响应时，仍在运行的尝试会立即终止，其截至当时所产生的流量也会计入。

标准流量同样不受请求结果影响：在设有带宽上限的套餐中，每个请求产生的流量都会计入该上限。因触及您自身套餐限制而被拒绝的请求则不计入任何流量。

## 隧道使用相同的术语体系

通过 [proxy 端口](https://foura.ai/docs/api/proxy-port)建立的隧道同样以这些结果之一结束，因此一套状态标签适用于两类产品。但七种结果中只有五种会出现，因为两种 `target` 结果需要 FourA 能够解析目标的响应，而隧道的响应属于您自身的加密流量。

| Outcome | On a tunnel, this means |
|---------|-------------------------|
| `success` | 隧道已建立，您的工具已成功接管。 |
| `client_error` | FourA 拒绝建立该隧道：私有或保留地址，或不支持的端口。 |
| `rate_limit` | 达到您套餐的某项配额限制（并发隧道数、每分钟新建隧道数、当前周期的标准流量、未包含的 premium 流量），或端口本身达到容量或连接速率上限。 |
| `service_error` | FourA 没有满足您请求的可用出口。通常为暂时性问题。 |
| `service_fail` | FourA 尝试的所有出口均无法连接到目标：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 | 无法访问私有及保留地址 |

隧道完全不以积分计费，因为隧道没有可供扣费的单个请求。端口改为按字节计量。请参阅 [套餐计费规则](https://foura.ai/docs/guides/plans-and-metering)。

## 在控制台中查看结果

您的 API Key 发起的每个请求都会显示在 [Activity](https://foura.ai/docs/dashboard/activity-log) 动态中，并带有其结果标签。[Metrics](https://foura.ai/docs/dashboard/metrics) 和 [Overview](https://foura.ai/docs/dashboard/overview) 页面会聚合这同一个字段，用于生成环形图和时间线。

当您按结果筛选 Activity 时，还可以聚焦于单个 endpoint (Auto, Single, Proxy Finder, Browser)，以查看某一类故障是否仅特定于其中某一个服务。将页面的 **Product** 切换为 Proxy，同样的结果标签即可筛选您的隧道。

## 重试策略参考

基于结果的初级重试策略：

| 结果 | 可否安全重试？ | 何时重试 |
|---------|-------------|------|
| `success` | 不适用 | 已获取响应。 |
| `application_error` | 视情况而定 | 查看目标网站的错误响应体。部分为暂时性错误，但多数不是。如果设置了 `X-FourA-Check-Page`，则说明网站返回了验证页面：请将 URL 发送至 Auto，Auto 会将验证页面视为待通过的步骤，而非最终响应。 |
| `application_fail` | 视情况而定 | 如果目标网站对您进行 rate limit，请降低请求频率。如果是拦截您，请切换至 Proxy 或 Browser endpoint。 |
| `client_error` | 否 | 请求仍会以相同方式失败。请修正输入参数。 |
| `rate_limit` | 视具体情况 | 遵循响应中给出的等待时间：`Retry-After`、`retry_after_seconds` 或 `retryAfter`。若遇到 `plan_limit_browser_daily`，请暂停请求直至 UTC 零点；若遇到 `plan_limit_credits` 或 `plan_limit_bandwidth`，请暂停直至 `resets_at`；若遇到 `plan_limit_feature` 或 `plan_limit_premium`，请修改请求。 |
| `service_error` | 是 | 采用简短的指数退避重试。 |
| `service_fail` | 是 | 与 `service_error` 相同。 |

## 相关内容

- [API 错误](https://foura.ai/docs/api/errors)：HTTP 级别错误响应
- [Proxy 端口](https://foura.ai/docs/api/proxy-port)：隧道拒绝连接时返回的状态码
- [Rate Limits](https://foura.ai/docs/api/rate-limits)：触发 `rate_limit` 的条件及其返回的两种形式
- [指标](https://foura.ai/docs/dashboard/metrics)：查看请求结果细分
- [活动日志](https://foura.ai/docs/dashboard/activity-log)：单次请求结果历史记录
