响应标头

来自 FourA API 的每个响应都包含一小组自定义标头。它们可用于追踪、支持、计费核对以及事后分析。

FourA 设置的标头

标头	适用范围	描述
`X-Foura-Request-Id`	每个 `/api/*` 响应，包括错误和 401 响应	用于标识此请求的 UUID。请在您这一端进行记录。
`X-FourA-Credits`	每个到达后端的 `/api/*` 响应	此调用消耗的额度。成功和失败时都会返回(无论哪种情况都已经执行了工作)。
`Content-Type`	每个响应	信封始终为 `application/json`。目标的 content-type 会在信封的 `headers` 字段中返回。

X-Foura-Request-Id

对 POST /api/auto/、POST /api/single/、POST /api/proxy/ 或 POST /api/browser/ 的每次调用都会标记一个 UUID。即使身份验证失败也会设置该标头，因此您也可以关联配置错误的调用。

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 会报告您刚才进行调用的额度成本。这是一个计量器，而不是账单：该标头反映了完成工作所消耗的成本，而无论结果如何。仪表板的计费层只会根据您的套餐计算可计费的结果(有关哪些结果可计费，请参见 Request Outcomes)。

成本参考

引擎	基础	使用 `unblocker`
Single	1	2
Proxy	5	10
Browser	15	30 (解决了防御时)

/api/auto/ 不会添加单独的可计费行。其额度成本是其在内部进行的子调用的总和(对热目标的单一重放可能以 2 完成；对困难站点的冷解析可能会消耗更多)。自动响应上的 X-FourA-Credits 值等于 body 中的 meta.credits，并跟踪完整的阶梯成本。

为什么同时提供标头和正文字段？

标头很方便：您可以在解析 body 之前读取它，将其记录在 request 行旁，或者在无需进行 JSON 解析的情况下跨多个调用对其求和。body 的 meta.credits (Auto)或每个引擎的元数据(Single、Proxy、Browser 仪表板)包含相同的数字，但在响应信封内具有可读性。

缓存行为

API 不会在响应上设置 Cache-Control 或 ETag。每次调用都会到达后端。如果您需要缓存，请在您一侧添加。

目标响应标头

目标站点返回的标头不在 FourA API 响应中。它们会在 JSON 信封内作为 headers 字段返回。对于 Single 和 Proxy endpoint，这是一个逐跳标头对象的数组(每个重定向步骤一个条目)。对于 Browser endpoint，它是最终响应标头的平面对象。

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

如果您需要特定的目标标头，请从信封的 headers 字段读取，而不是从 API 调用本身的 HTTP 响应中读取。