# Response Header

> URL: https://foura.ai/zh/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

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](https://foura.ai/docs/api/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，以便关联排查配置错误的调用。

```bash
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）](https://foura.ai/docs/dashboard/activity-log) 中，方便你打开对应行并检查捕获的 request 和 response。

### 示例：在本地记录日志

```python
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()
```

```javascript
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 都会反映执行任务所消耗的积分。控制面板的计费层仅将可计费结果计入您的套餐用量（有关哪些结果计费，请参见 [请求结果](https://foura.ai/docs/api/outcomes)）。

### 费用参考

| 引擎 | 基础 | 包含 `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 是唯一可以读取它的位置。每次调用的 [活动](https://foura.ai/docs/dashboard/activity-log)行也会显示该值。

## 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`，因为等待并不会改变结果。

```python
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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/activity-log) 行中的 **premium** 标记以及 [Usage & Limits](https://foura.ai/docs/dashboard/quota) 页面显示了具体计入的内容。有关 `exitClass` 的作用及何时使用高级出口的详情：[exitClass](https://foura.ai/docs/api/endpoints#exitclass)。

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

这两个 header 直接在响应中包含您的每日浏览器配额，与 [Usage & Limits](https://foura.ai/docs/dashboard/quota) 页面显示的数据相同，便于您追踪配额而无需轮询仪表板。

```
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](https://foura.ai/docs/api/rate-limits)。

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

## 缓存行为

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

## 目标响应 Headers

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

```json
{
  "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](https://foura.ai/docs/api/endpoints)：Request 和 response 信封结构
- [API Errors](https://foura.ai/docs/api/errors)：错误 response 的结构解析
- [Request Outcomes](https://foura.ai/docs/api/outcomes)：哪些结果计费
- [Activity Log](https://foura.ai/docs/dashboard/activity-log)：以 request ID 为键的单次 request 历史记录
- [Rate Limits](https://foura.ai/docs/api/rate-limits)：各个 `X-FourA-Limit` 值的具体含义
