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

只有 success 会消耗积分。Premium 流量与积分分开计算,不受 outcome 影响:参见 计费影响。

七种 Outcome

以下是一个 request 可能结束的七种状态。tunnel 使用其中的五种:参见下文 Tunnel 使用相同的词汇。

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 是我们侧的问题。请重试,如果持续出现,请检查 状态页。

目标站点返回 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

重定向循环(如第五行所示):

{
  "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,并将 meta.rung 设为 fail。

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

成功判定感知 validate

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

配置 validate 后,成功判定将遵循您声明的规则。如果您告知 API 针对某个指定 request,200 和 403 均可接受,则 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 并计费为一次请求。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 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 出口,就会计算该次尝试所产生的流量,因为出口均已被实际占用。当另一个出口已返回响应时,仍在运行的尝试会立即终止,其截至当时所产生的流量也会计入。

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

隧道使用相同的术语体系

通过 proxy 端口建立的隧道同样以这些结果之一结束,因此一套状态标签适用于两类产品。但七种结果中只有五种会出现,因为两种 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 无法访问私有及保留地址

隧道完全不以积分计费,因为隧道没有可供扣费的单个请求。端口改为按字节计量。请参阅 套餐计费规则。

在控制台中查看结果

您的 API Key 发起的每个请求都会显示在 Activity 动态中,并带有其结果标签。Metrics 和 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 相同。
更新于: 2026年11月11日