FourA API 的每个 response 都包含一组自定义 header。它们适用于链路追踪、技术支持、账单核对和事后分析。

FourA 设置的 Header

Header 设置时机 描述
X-FourA-Request-Id 每个 /api/* response,包括错误和 401,但在分配 ID 前即被拒绝的完全无法读取 body(400 Invalid JSON in request body,413)除外 标识此 request 的 UUID。建议在客户端记录该值。
X-FourA-Credits 到达后端的每个 /api/* response 本次调用消耗的积分。成功和失败时均会返回(两种情况下任务均已执行)。
X-FourA-Limit 由套餐配额限制触发的每个 403 或 429 拒绝该调用的具体限制:plan_limit_ 紧随 feature、premium、concurrency、rate、browser_daily、credits 或 bandwidth。
Retry-After 可通过等待恢复的套餐限制 429(并发、速率、积分、带宽)以及 503 API key check temporarily unavailable 等待秒数,为整数。与套餐限制 body 中的 retry_after_seconds 及 503 中的 retryAfter 匹配。
X-FourA-Exit-Class 指定了 exitClass 并成功返回页面的每个 /api/proxy/ 或 /api/auto/ 调用,以及通过高级出口提供服务的每个 Single 或 Browser 调用 premium 或 standard:传输 body 的出口类别。失败的 Proxy 调用未传输任何内容,因此不包含此项。
X-FourA-Browser-Used-Today 未被套餐限制拒绝的每个 POST /api/browser/ 应答,以及阶梯发出了未被拒绝 request 的每个 POST /api/auto/ 应答 账户今日计入的 Browser request 数量:详见下文。
X-FourA-Browser-Limit-Per-Day 在套餐设定了每日限额时的上述相同应答 套餐每日允许的 Browser request 数量。
X-FourA-Check-Page HTTP 200 body 属于 FourA 所识别的验证码或拒绝页面的 Single、Proxy Finder 和 Browser response 页面名称,例如 amazon-captcha。此类 request 不计费:参见 Request Outcomes。
Content-Type 每个 response 外层 envelope 始终为 application/json。目标的 content-type 在 envelope 的 headers 字段中返回。

X-FourA-Request-Id

每次调用 POST /api/auto/、POST /api/single/、POST /api/proxy/ 或 POST /api/browser/ 都会标记一个 UUID。即使身份验证失败也会设置该 header,以便关联排查配置错误的调用。

curl -i -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://example.com"}'
HTTP/1.1 200 OK
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

适用场景

  • 技术支持工单:附带 request ID,以便我们在记录中精准定位该次调用。
  • 自定义日志:将其与应用程序日志行一同存储。如果用户反馈“14:32 的数据有误”,你可以直接重放该请求。
  • 控制台链路追踪:相同的 ID 会显示在你所管理密钥的 动态流(Activity feed) 中,方便你打开对应行并检查捕获的 request 和 response。

示例:在本地记录日志

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

X-FourA-Credits 用于报告刚完成调用的积分消耗。它是一个计量器而非账单:无论结果如何,该 header 都会反映执行任务所消耗的积分。控制面板的计费层仅将可计费结果计入您的套餐用量(有关哪些结果计费,请参见 请求结果)。

费用参考

引擎 基础 包含 unblocker
Single 1 2
Proxy 2 4
Browser 5 10(完成防御验证时)

在控制面板中,/api/auto/ 计为一次请求,其积分消耗为其内部发起的子调用总和(预热目标上的单次重放可能以 2 结束;复杂站点上的冷启动破解可能会消耗更多)。auto 响应上的 X-FourA-Credits 值等于响应体中的 meta.credits,并跟踪完整的递进尝试成本。

为什么同时提供 header 和 body 字段?

Header 使用更便捷:您可以在解析响应体之前读取它、将其记录在请求行旁边,或者在无需解析 JSON 的情况下对多次调用求和。在 Auto 模式下,响应体中的 meta.credits 包含相同的数值。Single、Proxy 和 Browser 的响应体不包含该字段,因此在这些响应中,header 是唯一可以读取它的位置。每次调用的 活动行也会显示该值。

X-FourA-Limit

X-FourA-Limit 仅在您的套餐限制拒绝调用时才会出现。平台的共享 rate limit 绝不会设置此项,因此该 header 是区分“我的套餐拦截了该请求”还是“FourA 繁忙”的最快方式,无需解析响应体。

HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json

这七个值中有两个返回 403 而非 429:plan_limit_feature(该 endpoint 或 exitCountries 参数未包含在您的套餐中)和 plan_limit_premium(exitClass: premium 未包含在您的套餐中)。两者均不会设置 Retry-After,因为等待并不会改变结果。

STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))

这七个值以及各自附带的 body 字段均列在 Rate Limits 中。

X-FourA-Exit-Class

X-FourA-Exit-Class 用于指定交付 body 的出口类别:高级出口交付时为 premium,标准池交付时为 standard。只要请求指定了 exitClass,它就会出现在成功交付页面的 POST /api/proxy/ 或 POST /api/auto/ 响应中,此时 body 包含相同的值(Proxy 上为 exitClass,Auto 上为 meta.exitClass);只要你固定的 proxy 是高级出口,它也会出现在 Single 或 Browser 响应中,此时 body 中没有对应字段。失败的 Proxy 或 Auto 调用未提供任何内容,因此既不包含该 header,也不包含该字段。

HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json

通过高级出口的流量会计入您的高级流量以及总带宽。该数据在网络端测量,且包含未返回页面的高级尝试,因此以 standard 响应的 request 仍可能消耗了部分高级流量(发生在标准池响应前失败的尝试中)。此 header 指明提供交付的类别,而非是否使用了高级流量:Activity 行中的 premium 标记以及 Usage & Limits 页面显示了具体计入的内容。有关 exitClass 的作用及何时使用高级出口的详情:exitClass。

X-FourA-Browser-Used-Today 与 X-FourA-Browser-Limit-Per-Day

这两个 header 直接在响应中包含您的每日浏览器配额,与 Usage & Limits 页面显示的数据相同,便于您追踪配额而无需轮询仪表板。

HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json

计数在 UTC 午夜重置,并涵盖您方案下的所有密钥,而不仅是发起本次调用的密钥。因超出方案限制而被拒绝的 request 不包含上述任一 header:其响应体将包含 used_today 和 limit_per_day,详见 Rate Limits。

在 POST /api/browser/ 上,该计数包含您当前读取的 request。在 POST /api/auto/ 上,它是 ladder 运行期间所记录的最大计数值,因此可能会因您其他仍在运行的 request 而落后于当日实际用量。未发送实际 request 的 Auto 应答(例如目标站点多次失败后触发的 120 秒暂停)不包含上述任一 header。单次 Auto 调用所消耗的计数记录在 meta.browserRequests 中:详见 Smart Fetch。

缓存行为

API 不会设置 Cache-Control。response 可能会携带根据其响应体计算出的弱 ETag,但系统不会缓存任何内容:每次调用都会直接请求后端。如需缓存,请在客户端自行实现。

目标响应 Headers

目标站点返回的 header 不会直接出现在 FourA API 的 response 中。它们作为 headers 字段封装在 JSON 外层结构内返回。对于 Single 和 Proxy endpoint,这是一个由逐跳 header 对象组成的数组(每个重定向步骤对应一个条目)。对于 Browser endpoint,它是一个包含最终 response header 的扁平对象。

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

如果需要特定的目标 header,请从信封的 headers 字段中读取,而不是直接从 API 调用本身的 HTTP response 中读取。

更新于: 2026年11月5日