Header phản hồi

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ợ kỹ thuật, đối soát thanh toán và phân tích sau xử lý.

Các header FourA thiết lập

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 một UUID. Header này vẫn được thiết lập ngay cả khi xác thực thất bại, nhờ đó bạn cũng có thể liên kết các lệnh gọi bị cấu hình sai.

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

• Ticket hỗ trợ: đính kèm request ID và chúng tôi có thể tìm thấy chính xác lệnh gọi đó trong hệ thống ghi nhận.
• Log nội bộ: lưu ID cùng với 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 cho các key bạn quản lý, nhờ đó bạn có thể mở hàng tương ứng và kiểm tra request cũng như response đã ghi nhận.

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

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 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 để biết những kết quả nào được tính phí).

Tham chiếu chi phí

/api/auto/ là một request trên dashboard của bạn, với chi phí credit là tổng của các lệnh gọi phụ được thực hiện nội bộ (một lần replay đơn lẻ trên mục tiêu warm có thể dừng ở mức 2; một lần giải quyết cold trên trang web phức tạp có thể tốn nhiều hơn). Giá trị X-FourA-Credits trên response của auto bằng meta.credits trong body và theo dõi toàn bộ chi phí theo bậc.

Tại sao lại có cả trường header và body?

Header rất tiện lợi: bạn có thể đọc trước khi parse body, ghi log ngay cạnh dòng request hoặc tính tổng qua nhiều lệnh gọi mà không cần parse JSON. Trường meta.credits trong body (Auto) hoặc metadata theo từng engine (dashboard Single, Proxy, Browser) chứa cùng một con số, nhưng có thể đọc được bên trong cấu trúc response.

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 giữa "gói của tôi đã chặn lệnh này" và "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ị đi kèm với 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ả.

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 từng giá trị được nêu trong Rate Limits.

X-FourA-Exit-Class

X-FourA-Exit-Class chỉ định lớp exit đã phân phối body: premium khi exit premium 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/ đã phân phối trang bất cứ khi nào request chỉ định một exitClass, trong đó body chứa cùng giá trị đó, và trên response Single hoặc Browser bất cứ khi nào proxy bạn đã ghim là một exit premium, nơi body không có trường dành cho nó. Lời gọi Proxy không thành công sẽ không phục vụ 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 qua exit cao cấp được tính vào lưu lượng cao cấp cũng như tổng băng thông của bạn. Lưu lượng này được đo lường trên mạng và bao gồm cả các lần thử cao cấp 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 cao cấp, 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, không phải việc lưu lượng cao cấp có được sử dụng hay không: đánh dấu premium trên một hàng Activity và trang Usage & Limits hiển thị những gì đã được tính. Chức năng của exitClass và thời điểm exit cao cấp được sử dụng: exitClass.

Cache Behavior

API không thiết lập Cache-Control hoặc ETag trên response. Mọi lệnh gọi đều chuyển thẳng đến backend. Nếu bạn cần caching, hãy tự thêm vào phía bạn.

Target Response Headers

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

{
  "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 target header 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: Cấu trúc envelope của request và response
• API Errors: Cách các response lỗi được cấu trúc
• Request Outcomes: Những kết quả nào bị tính phí
• Activity Log: Lịch sử theo từng request được định danh bằng request ID
• Rate Limits: Ý nghĩa của từng giá trị X-FourA-Limit