# Response Header

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

Mỗi response từ FourA API đều bao gồm một tập hợp nhỏ các header tùy chỉnh. Chúng hữu ích cho việc tracing, hỗ trợ, đối soát thanh toán và phân tích sau sự kiện.

## Các Header Do FourA Thiết Lập

| Header | Được đặt trên | Mô tả |
|--------|--------|-------------|
| `X-FourA-Request-Id` | Mọi response `/api/*`, bao gồm các lỗi và lỗi 401, ngoại trừ body mà FourA hoàn toàn không thể đọc (`400 Invalid JSON in request body`, `413`), vốn bị từ chối trước khi ID được gán | Một UUID định danh request này. Hãy ghi log giá trị này ở phía bạn. |
| `X-FourA-Credits` | Mọi response `/api/*` đã tiếp cận được backend | Số credit đã tiêu tốn cho lệnh gọi này. Được trả về cả khi thành công lẫn thất bại (tác vụ đều đã được thực thi). |
| `X-FourA-Limit` | Mọi lỗi `403` hoặc `429` phát sinh do một trong các giới hạn gói cước của bạn | Giới hạn nào đã từ chối lệnh gọi: `plan_limit_` theo sau bởi `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits`, hoặc `bandwidth`. |
| `Retry-After` | Các lỗi `429` do giới hạn gói cước có thể giải quyết bằng cách chờ (concurrency, rate, credits, bandwidth) và lỗi 503 `API key check temporarily unavailable` | Số giây cần chờ, dưới dạng số nguyên. Khớp với `retry_after_seconds` trong body lỗi giới hạn gói cước và `retryAfter` trên lỗi 503. |
| `X-FourA-Exit-Class` | Mọi lệnh gọi `/api/proxy/` hoặc `/api/auto/` đã chỉ định một `exitClass` và phân phối thành công một trang, cùng mọi lệnh gọi Single hoặc Browser được phục vụ qua exit cao cấp | `premium` hoặc `standard`: phân loại của exit đã phân phối body. Lệnh gọi Proxy thất bại không phân phối nội dung nào và không mang header này. |
| `X-FourA-Browser-Used-Today` | Mọi phản hồi `POST /api/browser/` không bị giới hạn gói cước của bạn từ chối, và mọi phản hồi `POST /api/auto/` có ladder đã gửi một request không bị từ chối | Số lượng Browser request được tính hôm nay trên tài khoản của bạn: xem bên dưới. |
| `X-FourA-Browser-Limit-Per-Day` | Cùng các phản hồi đó, khi gói cước của bạn thiết lập giới hạn theo ngày | Số lượng Browser request mà gói cước của bạn cho phép mỗi ngày. |
| `X-FourA-Check-Page` | Các response Single, Proxy Finder và Browser có body HTTP 200 là trang kiểm tra bot hoặc trang từ chối mà FourA nhận diện | Tên của trang, ví dụ `amazon-captcha`. Request như vậy không bị tính phí: xem [Request Outcomes](https://foura.ai/docs/api/outcomes). |
| `Content-Type` | Mọi response | Luôn là `application/json` cho envelope. Content-type của đích đến được trả về bên trong trường `headers` của envelope. |

## X-FourA-Request-Id

Mỗi lệnh gọi tới `POST /api/auto/`, `POST /api/single/`, `POST /api/proxy/`, hoặc `POST /api/browser/` đều được gắn thẻ bằng một UUID. Header này được thiết lập ngay cả khi xác thực thất bại, giúp bạn có thể đối soát cả các lệnh gọi bị cấu hình sai.

```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
...
```

### Khi nào nên sử dụng

- **Yêu cầu hỗ trợ**: đính kèm request ID để chúng tôi có thể tìm chính xác lượt gọi trong bản ghi hệ thống.
- **Log của bạn**: lưu ID này cùng dòng log ứng dụng của bạn. Nếu khách hàng khiếu nại rằng "dữ liệu bị sai lúc 14:32", bạn có thể phát lại chính xác request đó.
- **Truy vết trên Dashboard**: cùng một ID này sẽ xuất hiện trong [Activity feed](https://foura.ai/docs/dashboard/activity-log) cho các key bạn quản lý, giúp bạn mở đúng hàng tương ứng và kiểm tra request cũng như response đã được ghi lại.

### Ví dụ: ghi log phía bạn

```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` báo cáo chi phí credit của lệnh gọi bạn vừa thực hiện. Đây là đồng hồ đo, không phải hóa đơn: header phản ánh mức tiêu hao của tác vụ bất kể kết quả ra sao. Lớp thanh toán trên dashboard chỉ tính các kết quả có tính phí vào gói của bạn (xem [Request Outcomes](https://foura.ai/docs/api/outcomes) để biết những kết quả nào được tính phí).

### Tham chiếu chi phí

| Engine | Base | With `unblocker` |
|--------|------|------------------|
| Single | 1 | 2 |
| Proxy | 2 | 4 |
| Browser | 5 | 10 (khi giải quyết được cơ chế phòng thủ) |

`/api/auto/` được tính là một request trên dashboard của bạn, với chi phí credit là tổng các sub-call nội bộ được thực hiện (một lần replay đơn lẻ trên warm target có thể kết thúc ở mức 2; một lượt solve nguội trên một trang web khó có thể tiêu tốn nhiều hơn). Giá trị `X-FourA-Credits` trên response tự động bằng với `meta.credits` trong body và theo dõi toàn bộ chi phí ladder.

### Tại sao lại có cả header lẫn trường body?

Header rất tiện lợi: bạn có thể đọc nó trước khi parse body, ghi log cùng dòng request, hoặc tính tổng qua nhiều lệnh gọi mà không cần parse JSON. Trên Auto, trường `meta.credits` của body chứa cùng một giá trị. Body của Single, Proxy và Browser không có trường này, vì vậy trên các response đó, header là nơi duy nhất để đọc nó. Hàng [Activity](https://foura.ai/docs/dashboard/activity-log) của mỗi lệnh gọi cũng hiển thị giá trị này.

## X-FourA-Limit

`X-FourA-Limit` chỉ xuất hiện khi một trong các giới hạn gói của bạn từ chối lệnh gọi. Rate limit dùng chung của nền tảng không bao giờ thiết lập header này, vì vậy đây là cách nhanh nhất để phân biệt "gói của tôi đã chặn yêu cầu này" với "FourA đang bận" mà không cần parse body.

```
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
```

Hai trong số bảy giá trị trả về mã 403 thay vì 429: `plan_limit_feature` (endpoint hoặc tham số `exitCountries` không có trong gói của bạn) và `plan_limit_premium` (`exitClass: premium` không có trong gói của bạn). Cả hai đều không thiết lập `Retry-After`, vì việc chờ đợi không làm thay đổi kết quả.

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

Bảy giá trị và các trường body đi kèm với mỗi giá trị được nêu trong [Rate Limits](https://foura.ai/docs/api/rate-limits).

## X-FourA-Exit-Class

`X-FourA-Exit-Class` đặt tên cho loại exit đã phân phối body: `premium` khi exit cao cấp thực hiện, `standard` khi pool tiêu chuẩn thực hiện. Header này xuất hiện trên response `POST /api/proxy/` hoặc `POST /api/auto/` đã phân phối một trang bất cứ khi nào request chỉ định một `exitClass`, trong đó body chứa cùng giá trị (`exitClass` trên Proxy, `meta.exitClass` trên Auto), và trên response Single hoặc Browser bất cứ khi nào `proxy` bạn ghim là một exit cao cấp, trong đó body không có trường dành cho giá trị này. Một lệnh gọi Proxy hoặc Auto thất bại không phân phối nội dung nào, do đó nó không chứa cả header lẫn trường này.

```
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
```

Lưu lượng truy cập qua premium exit được tính vào lưu lượng premium cũng như tổng băng thông của bạn. Lưu lượng được đo lường trên mạng và bao gồm cả các lần thử premium không trả về trang của bạn, do đó một request được phản hồi với `standard` vẫn có thể đã sử dụng một phần lưu lượng premium, trong một lần thử thất bại trước khi pool tiêu chuẩn phản hồi. Header này chỉ tên class đã phân phối dữ liệu, không thể hiện việc lưu lượng premium có được sử dụng hay không: dấu **premium** trên một hàng [Activity](https://foura.ai/docs/dashboard/activity-log) và trang [Usage & Limits](https://foura.ai/docs/dashboard/quota) hiển thị những gì đã được tính. Chức năng của `exitClass` và thời điểm premium exit được sử dụng: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today và X-FourA-Browser-Limit-Per-Day

Hai header này mang theo hạn mức trình duyệt hàng ngày của bạn ngay trên chính phản hồi, cùng các số liệu mà trang [Usage & Limits](https://foura.ai/docs/dashboard/quota) hiển thị, giúp bạn theo dõi mà không cần gửi request liên tục đến dashboard.

```
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
```

Số lượt đếm được đặt lại vào nửa đêm theo giờ UTC và áp dụng cho mọi key trong gói của bạn, không chỉ riêng key đã thực hiện lệnh gọi này. Một request bị từ chối do vượt giới hạn của gói sẽ không chứa cả hai header này: body của nó sẽ có `used_today` và `limit_per_day` để thay thế, xem [Rate Limits](https://foura.ai/docs/api/rate-limits).

Trên `POST /api/browser/`, số lượt đếm bao gồm chính request bạn đang xem. Trên `POST /api/auto/`, đó là số lượt đếm cao nhất mà ladder nhận được trong khi chạy, vì vậy nó có thể chậm hơn mức thực tế trong ngày do các request khác của bạn vẫn đang xử lý. Một phản hồi Auto không gửi bất kỳ request nào, chẳng hạn như khoảng dừng 120 giây sau các lần thất bại liên tiếp trên một trang web, sẽ không chứa cả hai header này. Số lượt mà một lệnh gọi Auto đã trừ vào tổng số được ghi trong `meta.browserRequests`: xem [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Hành vi Cache

API không thiết lập `Cache-Control`. Một response có thể mang một `ETag` yếu được tính toán từ body của nó, nhưng không có dữ liệu nào được cache: mọi lệnh gọi đều chuyển tiếp đến backend. Nếu bạn cần caching, hãy triển khai ở phía bạn.

## Target Response Headers

Các header do trang web mục tiêu trả về không nằm trên FourA API response. Chúng được trả về bên trong JSON envelope dưới dạng trường `headers`. Đối với các endpoint Single và Proxy, đây là một mảng chứa các đối tượng header theo từng chặng (mỗi bước redirect là một mục). Đối với endpoint Browser, đây là một flat object chứa các header của response cuối cùng.

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

Nếu bạn cần một header mục tiêu cụ thể, hãy đọc nó từ trường `headers` của envelope, không phải từ HTTP response của chính lệnh gọi API.

## Liên quan

- [API Endpoints](https://foura.ai/docs/api/endpoints): Cấu trúc envelope của request và response
- [API Errors](https://foura.ai/docs/api/errors): Cách định dạng error response
- [Request Outcomes](https://foura.ai/docs/api/outcomes): Những kết quả nào được tính phí
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): Lịch sử từng request theo request ID
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Ý nghĩa của từng giá trị `X-FourA-Limit`
