Response Header
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 中读取。
相关内容
- API Endpoints:Request 和 response 信封结构
- API Errors:错误 response 的结构解析
- Request Outcomes:哪些结果计费
- Activity Log:以 request ID 为键的单次 request 历史记录
- Rate Limits:各个
X-FourA-Limit值的具体含义