Các vấn đề 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 đích sử dụng JavaScript để render nội dung sau khi tải trang ban đầu.

Giải pháp: Chuyển từ single endpoint sang browser endpoint. 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

Triệu chứ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.

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

Mã lỗi 403 do trang đích trả về sẽ được phản hồi dưới dạng HTTP 200 kèm theo status: 403 bên trong body. Lỗi 403 trực tiếp trên lệnh gọi, kèm theo header X-FourA-Limit, lại là một trường hợp khác: xem 403 Not in Your Plan.

Lỗi Timeout

Triệu chứng: Các request thất bại kèm lỗi timeout.

Nguyên nhân: Trang đích mất nhiều thời gian tải hơn mức timeout đã 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, hãy 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 cùng header X-FourA-Limit và reason có giá trị plan_limit_feature hoặc plan_limit_premium.

{
  "error": "Geo targeting (the exitCountries parameter) 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 khi không có định vị địa lý (geo targeting); plan_limit_premium áp dụng cho exitClass: premium khi không có exit node cao cấp. Mục tiêu chưa từng được liên hệ, và bạn không bị trừ tài nguyên.

Giải pháp: Xóa tham số, gọi endpoint có trong gói dịch vụ của bạn, hoặc nâng cấp gói. Tab Limits & Features trong Usage & Limits liệt kê các tính năng gói của bạn hỗ trợ. Đừng thử lại nếu không thay đổi: không có Retry-After nào được đặt vì việc chờ đợi sẽ không làm thay đổi kết quả.

429 Too Many Requests

Triệu chứng: API trả về mã 429.

Nguyên nhân: Một trong hai quy trình kiểm tra đã từ chối lệnh gọi, và response sẽ cho biết đó là quy trình nào. Nếu response chứa header X-FourA-Limit, bạn đã đạt đến một trong các giới hạn của gói: 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/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. Hãy chờ khi thời gian giới hạn chỉ còn vài giây và dừng lại nếu không phải vậy. Các giới hạn gói có thể tự giải tỏa sau khi chờ sẽ ghi số giây trong header Retry-After và trong retry_after_seconds; giới hạn dùng chung sẽ ghi số giâ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 đồng thời đang mở và số lượng lệnh gọi bắt đầu mỗi phút thay vì thử lại liên tục. Việc gửi lại ngay một batch bị từ chối sẽ khiến toàn bộ batch đó bị từ chối tiếp. 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 liên tục gửi đến với tần suất gấp đôi giới hạn đó, các từ chối này sẽ chuyển thành cooldown: response body của mã 429 sẽ 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 Request Song Song cung cấp mẫu triển khai, và mục Usage & Limits trong Dashboard hiển thị bộ đếm trực tiếp cùng với các mức giới hạn của bạn.

503 Service Unavailable

Triệu chứng: API trả về trạng thái 503.

Nguyên nhân: Lỗi này xảy ra trong hai trường hợp:

Hệ thống đã đạt công suất tối đa. FourA đang chạy số lượng request trên engine đó chạm ngưỡng cho phép cùng một lúc, tính trên toàn bộ traffic chứ không chỉ riêng bạn. Service at capacity xuất hiện trong trường error. Tình trạng này thường tự giải tỏa trong vài giây.
Dịch vụ tạm thời bị vô hiệu hóa. Đang có đợt bảo trì hệ thống. Service disabled xuất hiện trong trường error.

Cả hai trường hợp đều đi kèm trường retryAfter trong response. Không trường hợp nào là do giới hạn gói cước: các giới hạn gói cước 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: Đợi trong 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")

Mã 503 at capacity nghĩa là FourA đang bận, vì vậy chỉ cần giãn cách thời gian và thử lại (backoff and retry). Nếu bạn bị từ chối với mã 429 và X-FourA-Limit, lỗi xuất phát từ phía bạn: hãy giảm số lượng request đồng thời trong pipeline của bạn.

504 Upstream Timeout

Hiện tượng: API trả về 504 kèm {"error": "Upstream timeout"}.

Nguyên nhân: Tác vụ không hoàn thành trong giới hạn thời gian (time budget) bạn đã cấu hình cho request. Mục tiêu phản hồi chậm, quá trình giải challenge lần đầu (cold challenge solve), hoặc một trang có dung lượng quá lớn đều có thể dẫn đến lỗi 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ời gian chờ cho lệnh gọi, hoặc thử lại. FourA sẽ đợi theo giá trị 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 sẽ 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ượt gọi cold call đầu tiên có thể mất vài chục giây. timeout_ms của nó bao gồm toàn bộ ladder 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ượt gọi vẫn trả về HTTP 200. 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 status riêng của nó tại đây). Hãy tăng timeout_ms hoặc thử lại.

502 Upstream Unavailable

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 đã kết nối được tới engine của chính nó nhưng không thể sử dụng phản hồi, thường là do một instance đang khởi động lại.

Giải pháp: Thử lại với thời gian backoff ngắn. Cả hai trường hợp đều được phân loại là service_error, và chỉ success mới bị tính phí, vì vậy việc thử lại không tốn thêm chi phí. Nếu tình trạng này kéo dài hơn một hoặc hai phút, hãy kiểm tra trang trạng thái.

Lỗi xác thực 401

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ải Authorization: Bearer hoặc Api-Key)
Kiểm tra khoảng trắng thừa hoặc ký tự dòng mới trong API key của bạn
Tạo một key mới từ Dashboard nếu key hiện tại có thể đã bị lộ

400 Mục tiêu phân giải ra IP riêng tư hoặc được bảo lưu

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 được bảo lưu (RFC 5735, RFC 6598, hoặc các khối IPv6 reserved). FourA từ chối các mục tiêu này để mạng của nó không bị lợi dụng để tiếp cận các host nội bộ.

Giải pháp: Fetch một URL công khai. Nếu bạn đang kiểm thử, hãy sử 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, trước tiên hãy mở nó ra một hostname công khai.

{ "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." }

Host name không thể tra cứu được sẽ không bị từ chối. Lời gọi API sẽ trả về HTTP 200 với status: 0 kèm theo lý do (could not resolve <host>: <reason>), tương tự 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í.

no_eligible_proxy khi dùng exitCountries

Triệu chứng: Một lệnh gọi /api/proxy/ có exitCountries trả về HTTP 200 kèm theo JSON error envelope:

{
  "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ó node thoát hoạt động nào có quốc gia hiển thị với mục tiêu khớp với allowlist của bạn. FourA không bao giờ dự phòng sang một quốc gia không được yêu cầu khi bạn đặt exitCountries.

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 phút một lần, vì vậy một quốc gia hiện không có kết nối 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 của quy trình làm việc thực sự thay đổi. Việc tự động chuyển dự phòng (fallback) sang các quốc gia khác mà không có cảnh báo có thể phá vỡ logic phụ thuộc vị trí địa lý ở các bước sau.

Body của response trả về văn bản bị lỗi font

Triệu chứng: Response data (hoặc body) chứa mojibake hoặc các ký tự không đọc được khi target sử dụng charset không phải UTF-8.

Nguyên nhân: Theo mặc định, FourA tự động giải mã body của response sang UTF-8 dựa trên header Content-Type hoặc thẻ HTML <meta charset> của target. Nếu target khai báo sai charset, bạn sẽ nhận được văn bản bị lỗi font.

Giải pháp: Đối với binary payload (hình ảnh, protobuf, raw audio), hãy đặt returnBuffer: true trên request. Khi đó Single và Proxy sẽ trả về data dưới dạng một đối tượng chứa raw bytes, {"type": "Buffer", "data": [<byte values>]}, mà không áp dụng chuyển đổi mã charset.

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

Đối với các mục tiêu văn bản khai báo sai charset, hãy tự decode các raw byte: fetch với returnBuffer: true, đọc các giá trị byte trong data.data, sau đó decode chúng bằng charset chính xác.

Nhận HTML ngoài dự kiến 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ể phân phát nội dung khác nhau dựa trên header.

Giải pháp: Thêm header Accept và bật unblocker để có các browser header thực tế:

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 Thử Thách, 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: Trang đích đã 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 cùng solved: false, còn Browser trả về defenseSolved: false với 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 profile trình duyệt khác trên Single, chuyển lên Proxy để có IP exit khác, hoặc sử 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: Kiểm tra trang web.

Thêm chuỗi con validate.data.accept mà chỉ trang thực sự mới có. Trang kiểm tra mà FourA nhận diện không bao giờ được tính là thành công: nó được trả về cùng 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ề mã HTTP 200, sẽ được tính là thành công, và bạn chỉ phát hiện ra ở quy trình xử lý 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ó sự cố nào đang diễn ra hay không
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-Id từ response thất bại)

Các Bước Tiếp Theo

Xử Lý Lỗi: Tài liệu tham khảo mã lỗi API
Rate Limit: Toàn bộ giới hạn gói và giới hạn nền tảng, kèm các trường
Kết Quả Request: Cách các kết quả phân loại những gì đã xảy ra
Kiểm tra trang web: Thông tin mà trường defense cung cấp cho bạn
Chọn Endpoint Phù Hợp: Chọn phương pháp tối ưu nhất cho trang đích của bạn
Tổng Quan Dashboard: Giám sát các request của bạn

Cập nhật: 30 tháng 9, 2026