请求结果
发往 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 相同。 |
相关内容
- API 错误:HTTP 级别错误响应
- Proxy 端口:隧道拒绝连接时返回的状态码
- Rate Limits:触发
rate_limit的条件及其返回的两种形式 - 指标:查看请求结果细分
- 活动日志:单次请求结果历史记录