Response Header
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. |
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.
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 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
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í
| 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 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ả.
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.
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 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 premium exit được sử dụng: 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 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.
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.
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.
{
"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: Cấu trúc envelope của request và response
- API Errors: Cách định dạng error response
- Request Outcomes: Những kết quả nào được tính phí
- Activity Log: Lịch sử từng request theo request ID
- Rate Limits: Ý nghĩa của từng giá trị
X-FourA-Limit