Các sự cố thường gặp
Giải pháp cho các vấn đề phổ biến nhất khi sử dụng FourA API.
Nội dung trống hoặc không đầy đủ
Triệu chứng: API trả về trạng thái 200 nhưng trường data bị trống hoặc thiếu nội dung dự kiến.
Nguyên nhân: Trang mục tiêu sử dụng JavaScript để kết xuất nội dung sau lần tải trang ban đầu.
Giải pháp: Chuyển từ endpoint đơn lẻ sang endpoint trình duyệt. Sử dụng checkText để xác minh nội dung đã tải:
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/products",
"timeout_ms": 15000,
"checkText": "product-list"
}'
Lưu ý: browser endpoint trả về nội dung trong trường body (không phải data).
403 Forbidden hoặc Trang xác minh
Hiện tượng: API trả về HTML chứa trang xác minh hoặc trang từ chối truy cập.
Nguyên nhân: Trang web đích đã phát hiện request là tự động và chặn nó.
Giải pháp: Sử dụng proxy endpoint để tự động xoay vòng IP:
curl -X POST https://eu.api.foura.ai/api/proxy/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maxTries": 5,
"request": {
"method": "GET",
"url": "https://example.com/prices",
"unblocker": true
}
}'
Nếu sự cố vẫn tiếp diễn, hãy tăng maxTries để hệ thống xoay vòng proxy có thêm số lần thử lại.
Lỗi 403 do mục tiêu trả về sẽ đến dưới dạng HTTP 200 kèm theo status: 403 bên trong body. Lỗi 403 trên chính lệnh gọi, đi kèm header X-FourA-Limit, lại là trường hợp khác: xem 403 Không có trong gói của bạn.
Lỗi Timeout
Triệu chứng: Các request thất bại do lỗi timeout.
Nguyên nhân: Trang mục tiêu mất nhiều thời gian tải hơn thời gian chờ được cấu hình.
Giải pháp: Tăng timeout_ms (mặc định là 15 giây cho single, 30 giây cho browser, 45 giây cho proxy):
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://slow-site.com",
"timeout_ms": 60000
}'
Đối với browser request, cũng cần xác minh giá trị checkText của bạn thực sự xuất hiện trên trang. Lỗi chính tả sẽ khiến lệnh gọi thất bại với checkText:<your text> not found.
403 Không có trong gói của bạn
Triệu chứng: API trả về 403 với header X-FourA-Limit và reason là plan_limit_feature hoặc plan_limit_premium.
{
"error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
Nguyên nhân: Gói dịch vụ của bạn không bao gồm endpoint bạn đã gọi hoặc tham số bạn đã gửi. plan_limit_feature áp dụng cho endpoint bị loại trừ, và exitCountries, exitState, exitCity, exitAsn hoặc exitOs không có định vị địa lý. plan_limit_premium áp dụng cho exitClass: premium không có cổng thoát cao cấp, và một request Proxy chỉ định một vị trí thoát khi lưu lượng cao cấp của bạn đã hết. Mục tiêu chưa từng được liên hệ và không có chi phí nào phát sinh.
Giải pháp: Xóa tham số, gọi endpoint có trong gói của bạn hoặc nâng cấp. Tab Limits & Features trong Usage & Limits liệt kê những gì gói của bạn bao gồm. Đừng thử lại khi chưa thay đổi: không có Retry-After nào được đặt vì việc chờ đợi không thay đổi kết quả.
429 Quá nhiều yêu cầu
Triệu chứng: API trả về 429.
Nguyên nhân: Một trong hai bước kiểm tra đã từ chối lệnh gọi, và response sẽ cho bạn biết bước nào. Nếu nó mang header X-FourA-Limit, một trong các giới hạn gói của bạn đã đạt mức tối đa: số request đồng thời hoặc số request mỗi phút trên endpoint đó, số request Browser trong ngày, hoặc số credit hay băng thông cho chu kỳ thanh toán. Nếu không có header này, hạn mức dùng chung mỗi phút của nền tảng cho dịch vụ đó đã đầy, điều này liên quan đến lưu lượng của FourA chứ không phải của bạn.
Giải pháp: Đọc X-FourA-Limit trước. Chờ đợi khi giới hạn chỉ còn cách vài giây và dừng lại khi không phải như vậy. Các giới hạn gói có thể được giải phóng sau thời gian chờ sẽ đặt số giây trong header Retry-After và trong retry_after_seconds; giới hạn dùng chung đặt số giây này trong retryAfter:
import time
import requests
# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}
def make_request(endpoint_url, payload, retries=3):
for i in range(retries):
resp = requests.post(
endpoint_url,
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json=payload
)
if resp.status_code == 429:
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
)
time.sleep(wait)
continue
return resp
raise Exception("Rate limit not resolved after retries")
# Example: single request
make_request(
"https://eu.api.foura.ai/api/single/",
{"method": "GET", "url": "https://example.com"}
)
Nếu header trả về plan_limit_concurrency hoặc plan_limit_rate, cách xử lý là giới hạn số lượng lệnh gọi đang mở đồng thời và số lượng bắt đầu mỗi phút thay vì thử lại dồn dập. Gửi lại ngay lập tức một batch đã bị từ chối sẽ khiến toàn bộ batch tiếp tục bị từ chối. Các lệnh gọi bị từ chối không tính vào giới hạn mỗi phút của bạn, nhưng nếu chúng tiếp tục được gửi đến với tần suất gấp hơn hai lần giới hạn đó, các phản hồi từ chối sẽ chuyển thành khoảng thời gian tạm dừng (cooldown): phần body của 429 chứa cooldown: true và yêu cầu bạn tạm dừng trong 30 giây (retry_after_seconds: 30). Chạy các request song song có hướng dẫn mô hình này, và mục Usage & Limits trong Dashboard hiển thị bộ đếm trực tiếp cạnh các giới hạn của bạn.
503 Dịch vụ không khả dụng
Hiện tượng: API trả về trạng thái 503.
Nguyên nhân: Lỗi này xảy ra trong ba trường hợp:
- Dịch vụ đã đạt giới hạn dung lượng. FourA đang chạy số lượng request trên engine đó chạm ngưỡng tối đa cho phép cùng lúc, được tính trên toàn bộ lưu lượng thay vì chỉ riêng bạn.
Service at capacityxuất hiện trong trườngerror. Tình trạng này thường hết sau vài giây. - Dịch vụ tạm thời bị vô hiệu hóa. Đang trong thời gian bảo trì hệ thống.
Service disabledxuất hiện trong trườngerror. - FourA tạm thời không thể kiểm tra key của bạn.
API key check temporarily unavailablexuất hiện trong trườngerror, đi kèmRetry-After: 5. Key của bạn vẫn hợp lệ.
Cả ba trường hợp đều bao gồm trường retryAfter trong response. Không có trường hợp nào liên quan đến giới hạn gói: các giới hạn thuộc gói của bạn luôn phản hồi bằng header X-FourA-Limit trên mã 403 hoặc 429, không bao giờ dùng 503.
Giải pháp: Chờ retryAfter giây, sau đó thử lại:
import time
import requests
def make_request_with_retry(endpoint_url, payload, retries=3):
for i in range(retries):
resp = requests.post(
endpoint_url,
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json=payload
)
if resp.status_code in (429, 503):
header = resp.headers.get("Retry-After")
body = resp.json()
wait = (
int(header) if header and header.isdigit()
else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
)
time.sleep(wait)
continue
return resp
raise Exception("Request not resolved after retries")
Lỗi 503 khi đầy tải nghĩa là FourA đang bận, vì vậy lùi lại và thử lại là giải pháp duy nhất. Nếu bạn bị từ chối với mã 429 và X-FourA-Limit, lỗi đó là từ phía bạn: hãy giảm số lượng request song song trong pipeline của bạn.
504 Hết thời gian chờ máy chủ ngược dòng (Upstream Timeout)
Hiện tượng: API trả về 504 với {"error": "Upstream timeout"}.
Nguyên nhân: Quá trình xử lý không hoàn thành trong khoảng thời gian bạn đã thiết lập cho request. Đích đến phản hồi chậm, giải thử thách lần đầu (cold challenge solve), hoặc trang quá lớn đều có thể gây ra điều này. Đây không phải là vấn đề với key, tham số, hay proxy của bạn.
Giải pháp: Tăng thêm thời gian cho lệnh gọi, hoặc thử lại. FourA sẽ chờ theo timeout_ms của bạn cộng thêm một khoảng trừ hao nhỏ, do đó việc tăng giá trị này thực sự kéo dài thời gian chờ:
{
"url": "https://slow-site.com/report",
"timeout_ms": 90000
}
Đối với /api/auto/ trên một mục tiêu được bảo vệ, lệnh gọi nguội đầu tiên có thể mất hàng chục giây. timeout_ms của lệnh gọi bao quát toàn bộ quy trình và chấp nhận tối đa 180000.
Khi chính /api/auto/ dùng hết ngân sách thời gian đó, lệnh gọi vẫn trả lời HTTP 200. Phần body chứa một error bắt đầu bằng time budget exhausted, và status thường là 504 (một lần thử thất bại trước đó có thể để lại mã trạng thái riêng tại đây). Hãy tăng timeout_ms hoặc thử lại.
502 Upstream Không Khả Dụng
Triệu chứng: API trả về 502 với {"error": "Upstream unavailable"}, hoặc 503 với {"error": "Backend service unavailable"}.
Nguyên nhân: FourA không thể kết nối tới engine của chính nó (Upstream unavailable), hoặc engine không trả về câu trả lời khả dụng (Backend service unavailable), thường là do một instance đang khởi động lại. Trên /api/browser/, một trang sẽ đợi tối đa 10 giây để có trình duyệt trống khi tất cả đều đang bận, và trang vẫn tiếp tục phải đợi sau khoảng thời gian đó sẽ trả về lỗi 503 này.
Giải pháp: Thử lại với khoảng thời gian lùi (backoff) ngắn. Cả hai đều được phân loại là service_error, và chỉ success mới bị tính phí, vì vậy lần thử lại sẽ không tốn thêm chi phí. Nếu tình trạng kéo dài hơn một hoặc hai phút, hãy kiểm tra trang trạng thái.
401 Lỗi Xác Thực
Triệu chứng: Mọi request đều trả về 401 Unauthorized.
Danh sách kiểm tra:
- Xác minh header là
X-API-Key: YOUR_API_KEY(không phảiAuthorization: BearerhoặcApi-Key) - Kiểm tra khoảng trắng thừa hoặc ký tự xuống dòng trong API key của bạn
- Tạo một key mới từ Dashboard nếu key hiện tại có nguy cơ bị lộ
400 Request Không Hợp Lệ
Triệu chứng: Một lệnh gọi POST /api/single/, /api/proxy/ hoặc /api/browser/ trả về 400 với {"error": "Invalid request: <field>: <reason>; ..."}.
Nguyên nhân: Một trường trong body của request bị thiếu, sai kiểu dữ liệu hoặc nằm ngoài phạm vi cho phép. Thông báo nêu rõ từng trường không được chấp nhận và lý do, tối đa năm trường, kèm theo and N more khi còn các lỗi khác. Không có nội dung nào được tải về, kết quả là client_error, và không có credit nào bị trừ.
Giải pháp: Sửa các trường được nêu và gửi lại request. Request có cùng body sẽ tiếp tục nhận mã 400, vì vậy đừng thử lại khi chưa sửa đổi. Tài liệu tham khảo endpoint liệt kê mọi trường cùng kiểu dữ liệu và giới hạn. Trên /api/auto/ cùng một lỗi này sẽ trả về HTTP 200 với status: 400 và lý do nằm trong error.
400 Mục Tiêu Phân Giải Thành IP Riêng Tư Hoặc Dành Riêng
Triệu chứng: API trả về 400 với Refusing to fetch <target>: target resolves to a private or reserved IP range trước khi request rời khỏi FourA.
Nguyên nhân: url của bạn phân giải thành một dải IP riêng tư, loopback, hoặc dành riêng (RFC 5735, RFC 6598, hoặc các khối IPv6 dành riêng). FourA từ chối các mục tiêu này để mạng của dịch vụ không bị dùng để truy cập vào các host nội bộ.
Giải pháp: Tải một URL công khai. Nếu bạn đang thử nghiệm, hãy dùng một mục tiêu công khai như https://example.com hoặc https://httpbin.org/get. Nếu mục tiêu dự kiến là một dịch vụ do bạn vận hành, hãy đưa dịch vụ đó lên một hostname công khai trước.
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
Tên máy chủ không thể tra cứu được sẽ không bị từ chối. Lời gọi API trả về dưới dạng HTTP 200 kèm status: 0 và lý do (could not resolve <host>: <reason>), giống như bất kỳ mục tiêu nào FourA không thể tiếp cận, và nó không bị tính phí.
400 Khoảng trắng trong URL
Triệu chứng: Single, Proxy hoặc Auto trả về mã lỗi 400 kèm invalid URL: it contains a space; encode it as %20 (the URL as sent: "...") trước khi request rời khỏi FourA.
Nguyên nhân: URL chứa khoảng trắng hoặc ký tự điều khiển bên trong, thường là liên kết lấy nguyên văn từ một trang (javascript: void(0), liên kết chia sẻ có chứa văn bản). Không có nội dung nào được tìm nạp, kết quả là client_error, và không bị trừ credit.
Giải pháp: Mã hóa URL trước khi gửi (khoảng trắng là %20), và bỏ qua các liên kết không phải là trang web, như liên kết javascript:. Trình duyệt tìm nạp URL như vậy theo cách Chrome thực hiện.
400 Mục tiêu chính là FourA API
Triệu chứng: API trả về 400 kèm Refusing to fetch <url>: that is the FourA API itself, not a page. trước khi request rời khỏi FourA.
Nguyên nhân: url của bạn trỏ tới api.foura.ai hoặc eu.api.foura.ai. Một crawler thường làm điều này khi phân giải một liên kết tương đối từ trang web dựa trên URL API thay vì URL riêng của trang, vì vậy /category/news/ biến thành https://eu.api.foura.ai/category/news/. Không có nội dung nào được tìm nạp và không bị trừ credit.
Giải pháp: Phân giải mọi liên kết dựa trên URL của trang nguồn trước khi gửi, ví dụ dùng urljoin(page_url, href) trong Python. Inspect endpoint (/inspect) là địa chỉ duy nhất trên host API mà bạn có thể tìm nạp qua FourA.
no_eligible_proxy khi dùng exitCountries
Triệu chứng: Một lời gọi /api/proxy/ kèm exitCountries trả về HTTP 200 với một cấu trúc JSON lỗi:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
Nguyên nhân: Proxy pool hiện tại không có exit node nào đang hoạt động với quốc gia hiển thị tới mục tiêu khớp với danh sách cho phép của bạn. Pool tiêu chuẩn không bao giờ tự động chuyển sang một quốc gia không được yêu cầu khi bạn đặt exitCountries. Nếu không có exitCountries, trường hợp tương tự sẽ trả về {"error": "Failed"}: FourA không có exit node nào để thử, vì vậy hãy thử lại sau vài giây.
Một request chỉ định vị trí exit node (exitState, exitCity, exitAsn, exitOs hoặc exitLifetimeMin, cùng với exitClass: premium) chỉ đi qua các exit node cao cấp. Khi FourA không còn exit node cao cấp nào khả dụng để thử cho request đó, lệnh gọi sẽ kết thúc với "error": "No premium exit answered for this request" và code: no_eligible_proxy tương tự.
Giải pháp: Giữ nguyên phạm vi đã yêu cầu và thử lại sau. Pool được làm mới khoảng mỗi mười phút một lần, do đó một quốc gia hiện không có exit node phù hợp thường sẽ có lại trong vòng một giờ.
import time, requests
def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
for _ in range(max_attempts):
r = requests.post("https://eu.api.foura.ai/api/proxy/",
headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={"maxTries": 5, "exitCountries": countries,
"request": {"method": "GET", "url": url}}).json()
if r.get("code") == "no_eligible_proxy":
time.sleep(wait_sec)
continue
return r
raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
Chỉ mở rộng danh sách quốc gia nếu yêu cầu quốc gia trong quy trình của bạn thực sự thay đổi. Việc tự động chuyển dự phòng sang các quốc gia khác có thể phá vỡ logic phụ thuộc vào vị trí địa lý ở các bước tiếp theo.
Browser Profile Bị Từ Chối
Triệu chứng: Lời gọi trả về lỗi unknown profile '<id>', no profile matches browser=..., hoặc browser profile selection requires unblocker:true.
Nguyên nhân: profile, browser, os hoặc version bạn gửi không có trong danh mục, hoặc bạn đã gửi cùng với unblocker: false.
Giải pháp: Xem GET /api/profiles để biết danh mục hiện tại, chọn từ đó, và duy trì bật unblocker khi bạn chọn một trình duyệt.
Nội Dung Response Bị Lỗi Ký Tự
Triệu chứng: data (hoặc body) của response chứa ký tự mojibake hoặc không đọc được khi mục tiêu sử dụng charset khác UTF-8.
Nguyên nhân: Theo mặc định, FourA tự động giải mã nội dung response sang UTF-8 dựa trên header Content-Type của mục tiêu hoặc thẻ HTML <meta charset>. Nếu mục tiêu khai báo sai charset, bạn sẽ nhận về văn bản bị lỗi.
Giải pháp: Đối với dữ liệu nhị phân (hình ảnh, protobuf, âm thanh thô), hãy đặt returnBuffer: true trên request. Single và Proxy sau đó sẽ trả về data dưới dạng một object chứa các byte thô, {"type": "Buffer", "data": [<byte values>]}, và không áp dụng chuyển mã charset.
{
"method": "GET",
"url": "https://example.com/image.png",
"returnBuffer": true
}
Đối với các mục tiêu dạng văn bản khai báo sai charset, hãy tự giải mã các byte thô: gửi request với returnBuffer: true, đọc các giá trị byte trong data.data, sau đó giải mã chúng bằng đúng charset.
Nhận được HTML thay vì JSON
Triệu chứng: Bạn mong đợi JSON từ trang web mục tiêu nhưng lại nhận được HTML.
Nguyên nhân: Trang mục tiêu có thể trả về nội dung khác nhau dựa trên các header.
Giải pháp: Thêm header Accept và bật unblocker để có các browser header chân thực:
curl -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://api.example.com/data",
"headers": [["Accept", "application/json"]],
"unblocker": true
}'
Bạn cũng có thể đặt tryJsonData thành true để FourA tự động phân tích cú pháp các response JSON.
Body là trang challenge, không phải nội dung
Triệu chứng: Lời gọi thành công, status là 200, nhưng data (hoặc body) là trang kiểm tra bot thay vì trang bạn cần.
Nguyên nhân: Mục tiêu đã chạy quy trình kiểm tra bot mà FourA gặp phải nhưng không thể vượt qua. Response thể hiện rõ điều này: Single và Proxy trả về defense với solved: false, còn Browser trả về defenseSolved: false cùng nhà cung cấp trong defenses.present.
Giải pháp: Kiểm tra defense.vendor trước, sau đó nâng cấp giải pháp. Thử một browser profile khác trên Single, chuyển lên Proxy để có IP exit khác, hoặc dùng Browser để JavaScript được thực thi. Tài liệu tham khảo đầy đủ về các trường và danh sách nhà cung cấp: Site checks.
Thêm một chuỗi con validate.data.accept mà chỉ trang thực sự mới có. Một trang kiểm tra mà FourA nhận diện được sẽ không bao giờ được tính là thành công: nó trả về kèm header X-FourA-Check-Page và không bị tính phí. Nếu không có validate, một trang kiểm tra mà FourA không nhận diện được, trả về với HTTP 200, sẽ được tính là thành công, và bạn chỉ phát hiện ra ở quy trình phía sau thay vì ngay tại thời điểm gọi.
Vẫn gặp sự cố?
Nếu không có giải pháp nào ở trên hiệu quả:
- Kiểm tra trang trạng thái để xem các sự cố đang diễn ra
- Xem lại các chỉ số request của bạn trong Dashboard
- Liên hệ bộ phận hỗ trợ tại support@foura.ai cùng thông tin chi tiết về request của bạn (bao gồm
X-FourA-Request-Idtừ response lỗi)
Các bước tiếp theo
- Error Handling: Tài liệu tham khảo mã lỗi API
- Rate Limits: Toàn bộ giới hạn gói và giới hạn nền tảng, kèm các trường
- Request Outcomes: Cách outcomes phân loại điều đã xảy ra
- Site checks: Thông tin mà trường
defensecung cấp - Choosing the Right Endpoint: Chọn phương pháp tối ưu cho mục tiêu của bạn
- Dashboard Overview: Giám sát các request của bạn