Mỗi request gửi đến FourA API đều trải qua ba bước kiểm tra trước khi đến được engine: giới hạn gói của bạn, định mức dùng chung của nền tảng cho toàn bộ lưu lượng, và định mức dùng chung của nền tảng cho endpoint bạn đã gọi. Mỗi bước kiểm tra đều có thể tự từ chối request, và mỗi bước sẽ phản hồi với một body khác nhau.

Ba bước kiểm tra theo thứ tự

  1. Giới hạn gói. Những gì gói của bạn cho phép: bao gồm những endpoint và tham số nào, bao nhiêu request có thể chạy đồng thời trên mỗi endpoint, bao nhiêu request mỗi phút, bao nhiêu browser request mỗi ngày, cùng số credit và băng thông khả dụng trong chu kỳ thanh toán.
  2. Giới hạn toàn hệ thống của nền tảng. Toàn bộ lưu lượng mà API host bạn gọi đang xử lý tại thời điểm đó, bất kể lưu lượng gửi đến endpoint nào. Việc từ chối tại đây sẽ trả về "service": "api".
  3. Giới hạn endpoint của nền tảng. Lưu lượng trên dịch vụ single, proxy hoặc browser mà bạn đã gọi.

Gói của bạn luôn được đánh giá trước tiên, và thứ tự này là một cam kết trong thỏa thuận chứ không phải chi tiết triển khai tùy biến. Các định mức dùng chung là tài nguyên chung, vì vậy một request mà nền tảng chắc chắn sẽ từ chối không được phép tiêu tốn tài nguyên này trước khi bị từ chối. Một tài khoản gửi vượt quá mức cho phép của gói sẽ bị chặn trước khi tác động đến tài nguyên của người khác.

Bước kiểm tra 2 và 3 tính tổng lưu lượng của FourA, không phải của riêng bạn. Hãy hiểu phản hồi từ chối từ một trong hai bước này là "FourA đang bận", chứ không phải "bạn đã gửi quá nhiều". Bước kiểm tra 1 chỉ áp dụng cho riêng tài khoản của bạn, và không có yếu tố nào khác trên nền tảng làm thay đổi nó.

Phản hồi từ chối từ bất kỳ bước kiểm tra dùng chung nào đều sẽ hoàn trả lại toàn bộ hạn mức mà lượt tiếp nhận đã tính, bao gồm cả bucket theo phút lẫn slot browser theo ngày, vì request chưa từng chạm tới backend. Trường hợp này cũng không tính vào thời gian tạm dừng thử lại được mô tả trong Requests per minute: request bị từ chối do dung lượng của FourA, không phải do gói của bạn.

POST /api/auto/ không giữ slot riêng. Các sub-call Single, Proxy và Browser mà nó tạo cho bạn đều phải vượt qua cả ba bước kiểm tra như mọi request khác, do đó một loạt lệnh gọi auto song song sẽ tính vào gói của bạn thông qua các sub-call này. (Số lượng request và tỷ lệ thành công của bạn tính riêng lệnh gọi auto một lần; các sub-call được hiển thị dưới dạng các lần thử của lệnh gọi đó.)

Giới hạn gói

Phản hồi vi phạm giới hạn gói sẽ đi kèm header X-FourA-Limit nêu rõ giới hạn nào đã từ chối lệnh gọi. Mã tương tự cũng xuất hiện trong body dưới trường reason, giúp bạn có thể rẽ nhánh xử lý mà không cần đọc header. Mọi body phản hồi giới hạn gói đều chứa error, reason, và documentation; các trường còn lại sẽ tùy thuộc vào từng giới hạn.

X-FourA-Limit Trạng thái Tài nguyên đã hết
plan_limit_feature 403 Endpoint bạn đã gọi, hoặc tham số exitCountries, exitState, exitCity, exitAsn hoặc exitOs, không có trong gói của bạn
plan_limit_premium 403 exitClass: premium không có trong gói của bạn, hoặc một request Proxy chỉ định exit location khi lưu lượng cao cấp đã hết
plan_limit_concurrency 429 Request đồng thời trên endpoint đó
plan_limit_rate 429 Request mỗi phút trên endpoint đó
plan_limit_browser_daily 429 Request trình duyệt trong ngày
plan_limit_credits 429 Credit tính phí trong chu kỳ thanh toán
plan_limit_bandwidth 429 Băng thông trong chu kỳ thanh toán

Các con số cụ thể cho từng hạn mức tùy thuộc vào gói của bạn, và tab Limits & Features trong Usage & Limits liệt kê chúng cạnh mức sử dụng trực tiếp của bạn. Đừng hardcode chúng: mỗi phản hồi từ chối đều đi kèm giới hạn trần đã từ chối nó.

Một request bị từ chối sẽ không tốn chi phí nào. Kết quả là rate_limit, và chỉ success mới bị tính phí.

Endpoint hoặc tham số không có trong gói

Mã 403 với plan_limit_feature nghĩa là lệnh gọi đã yêu cầu tính năng mà gói không bao gồm. Việc kiểm tra diễn ra trước khi tính toán bất kỳ điều gì, vì vậy lệnh gọi bị từ chối không ảnh hưởng đến bộ đếm rate limit hoặc bộ đếm hàng ngày của bạn.

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

Cùng một mã và trạng thái sẽ phản hồi cho một lệnh gọi POST /api/proxy/ thiết lập exitCountries, exitState, exitCity, exitAsn hoặc exitOs trên một gói không có định vị địa lý (geo targeting). Chuỗi error sẽ nêu tên tham số:

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

plan_limit_premium có định dạng tương tự cho exitClass: premium trên gói cước không có premium exit. Gói cước bao gồm premium exit nhưng đã dùng hết lưu lượng premium của kỳ này sẽ không bị từ chối, trừ khi một Proxy request chỉ định vị trí exit: request sẽ được phục vụ từ pool tiêu chuẩn và response sẽ trả về exitClass: standard. Cả hai trường hợp đều không tiêu tốn premium exit. Xem exitClass.

Cả hai mã 403 đều không đặt Retry-After. Việc chờ đợi không làm thay đổi kết quả.

Simultaneous requests

Concurrency được tính theo từng endpoint: gói cước của bạn có một giới hạn trần cho Single, một cho Proxy và một cho Browser. Request vượt quá giới hạn sẽ trả về mã 429 kèm Retry-After: 1:

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

in_flight cũng tính cả request bị từ chối, vì vậy giá trị này sẽ cao hơn limit ít nhất một đơn vị.

Cách khắc phục là giới hạn mức độ song song của chính bạn thay vì thử lại dồn dập hơn. Phản hồi lại mã 429 bằng cách gửi lại ngay cùng một batch sẽ tạo ra một mã 429 khác cho mỗi lệnh gọi trong đó. Xem Chạy Request Song Song để biết pattern mẫu đã hoạt động.

Request mỗi phút

Single và Proxy áp dụng định mức theo phút, được đo theo một phút trượt (sliding minute). Chỉ các request được chấp nhận mới được tính: request bị từ chối sẽ được loại trừ ra, do đó tài khoản gửi yêu cầu đều đặn vượt quá định mức một chút vẫn sẽ được phục vụ theo đúng định mức thay vì bị từ chối hầu như toàn bộ.

{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}

retry_after_seconds là khoảng thời gian cho đến khi một request tiếp theo được chấp nhận, nếu bạn không gửi thêm gì khác ở giữa: tối thiểu 1 giây và tối đa 120 giây. Header Retry-After chứa cùng một giá trị.

Việc thử lại các request bị từ chối nhanh hơn mức đó có quy tắc riêng. Khi số request mà hạn mức này đã từ chối trong một phút trượt vượt quá hai lần hạn mức, lệnh gọi sẽ bị từ chối kèm thời gian tạm dừng 30 giây:

{
  "error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 540,
  "refused_last_minute": 1250,
  "cooldown": true,
  "retry_after_seconds": 30
}

Các lần từ chối trong thời gian tạm dừng không được tính, do đó thời gian tạm dừng sẽ tự kết thúc khi hết phút, ngay cả đối với client liên tục thử lại. Để phân biệt thời gian tạm dừng với hạn mức thông thường, hãy đọc cooldown thay vì nội dung error.

Browser request mỗi ngày

Browser không có hạn mức theo phút. Giới hạn gói dịch vụ của Browser là số lượng browser request mỗi ngày, tính từ nửa đêm UTC, và bộ đếm sẽ ghi nhận mọi browser request được chấp nhận, không chỉ các request thành công. Một lệnh gọi Browser thất bại từ phía FourA mà không tốn credit, chẳng hạn như lỗi 503 Backend service unavailable, sẽ hoàn lại slot trong ngày đó. Các phản hồi từ Browser và Auto không bị giới hạn từ chối sẽ mang theo số lượng và giới hạn trong các header X-FourA-Browser-Used-Today và X-FourA-Browser-Limit-Per-Day: xem Response Headers.

{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}

Phản hồi từ chối này không chứa header retry_after_seconds cũng như Retry-After, vì thời gian chờ kéo dài hàng giờ thay vì vài giây. Hãy xem đây là lệnh dừng và lên lịch cho lần chạy tiếp theo vào lúc nửa đêm UTC.

Credit cho chu kỳ thanh toán

Chỉ các credit bị tính phí mới được tính, nghĩa là chỉ các request thành công. Khi tổng số credit bị tính phí đạt đến giới hạn credit khả dụng của bạn trong chu kỳ này, các request tiếp theo sẽ bị từ chối cho đến khi chu kỳ được đặt lại hoặc bạn mua thêm.

{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

hard_stop là số lượng credit tính phí mà tại đó các request sẽ bị dừng trong chu kỳ này. Hãy đọc giá trị này từ body thay vì tự tính toán: nó đã bao gồm mọi credit bạn mua thêm ngoài gói dịch vụ.

Băng thông cho chu kỳ thanh toán

Các gói dịch vụ có giới hạn băng thông sẽ từ chối request khi lưu lượng tiêu chuẩn trong chu kỳ này đạt mức giới hạn. Lưu lượng Premium có hạn mức riêng và không tính vào giới hạn này. Băng thông mua thêm được tính tương tự như băng thông đi kèm trong gói, và chuỗi error biểu thị dung lượng khả dụng cho bạn, không chỉ riêng phần đi kèm của gói dịch vụ.

{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

Trên cả hai giới hạn chu kỳ, retry_after_seconds được giới hạn tối đa ở 24 giờ; resets_at là thời điểm chính xác khi chu kỳ được làm mới.

Các trường giới hạn gói dịch vụ

Field Type Present on Description
error string all Thông báo dễ đọc, bao gồm giới hạn áp dụng cho bạn
reason string all plan_limit_ kèm tên giới hạn. Cùng giá trị với header X-FourA-Limit.
documentation string all Liên kết đến trang các gói dịch vụ
retry_after_seconds number concurrency, rate, credits, bandwidth Thời gian cần chờ. Cùng giá trị với header Retry-After.
limit number concurrency Số request đồng thời gói dịch vụ cho phép trên endpoint đó
in_flight number concurrency Số request đang chạy trên endpoint đó cho tài khoản của bạn, bao gồm cả request bị từ chối
limit_per_minute number rate Số request mỗi phút gói dịch vụ cho phép trên endpoint đó
current_rate number rate Số request được tính trong cửa sổ trượt 1 phút, bao gồm cả request bị từ chối
refused_last_minute number rate pause Số request bị định mức mỗi phút từ chối trong cửa sổ trượt 1 phút. Chỉ xuất hiện khi tạm dừng 30 giây.
cooldown boolean rate pause true khi tạm dừng 30 giây do retry quá nhanh. Không xuất hiện khi bị từ chối theo phút thông thường.
limit_per_day number browser daily Số browser request gói dịch vụ cho phép mỗi ngày
used_today number browser daily Số browser request được tính trong ngày hôm nay, bao gồm cả request bị từ chối
used number credits Credit đã tính phí cho đến nay trong chu kỳ này
hard_stop number credits Mức credit tính phí khiến request bị dừng lại trong chu kỳ này
used_bytes number bandwidth Lưu lượng standard cho đến nay trong chu kỳ này, tính bằng byte. Không bao gồm lưu lượng premium.
limit_bytes number bandwidth Số byte còn khả dụng trong chu kỳ này
resets_at string credits, bandwidth Dấu thời gian ISO 8601 của thời điểm kết thúc chu kỳ

Giới hạn gói dịch vụ sử dụng retry_after_seconds. Các giới hạn nền tảng bên dưới sử dụng retryAfter. Trình xử lý retry cần đọc cả hai, hoặc đọc header Retry-After, vốn được thiết lập bởi giới hạn gói dịch vụ và mã 503 API key check temporarily unavailable (xem Errors).

Giới hạn nền tảng

Cơ chế kiểm tra của nền tảng theo dõi hai chỉ số cho mỗi dịch vụ và thêm một chỉ số nữa trên tất cả dịch vụ:

  • Concurrency: số lượng request FourA đang xử lý cùng một lúc.
  • RPM: số lượng request FourA đã tiếp nhận trong 60 giây qua.

Cả hai bộ đếm đều được dùng chung bởi tất cả người dùng dịch vụ đó. current và limits trong các response bên dưới mô tả nền tảng, không phải tài khoản của bạn. Nếu bạn muốn kiểm tra số liệu của riêng mình, hãy đọc in_flight từ response của giới hạn gói dịch vụ, hoặc mở mục Usage & Limits trong dashboard.

429: Vượt quá RPM

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Dịch vụ đã đạt giới hạn request cho phép trong một phút qua. Chờ retryAfter giây.

503: Vượt quá giới hạn đồng thời

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Dịch vụ đang xử lý số lượng request tối đa được phép cùng một lúc. Tình trạng này sẽ hết sau vài giây.

Dịch vụ bị vô hiệu hóa

Khi một dịch vụ tạm thời ngoại tuyến để bảo trì, API sẽ trả về mã 503 kèm theo thông báo lỗi khác:

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

Đây không phải là lỗi rate limit. Dịch vụ tạm thời không khả dụng. Kiểm tra giá trị retryAfter và thử lại sau số giây đó. Tình trạng này thường được xử lý trong vài phút.

Cả hai định dạng phản hồi 503 đều chứa các khóa giống nhau, vì vậy hãy phân nhánh dựa trên chuỗi error và không bao giờ dựa vào sự hiện diện của các trường. Service disabled là bảo trì, Service at capacity là số lượng yêu cầu đồng thời.

Ở định dạng bảo trì, current.concurrency và current.rpm luôn là 0: request đã bị từ chối trước khi bất kỳ thông số nào được đo lường.

Các trường giới hạn nền tảng

Field Type Description
error string Thông báo lỗi con người có thể đọc hiểu
status number Mã trạng thái HTTP (429 hoặc 503)
service string Dịch vụ đã từ chối lệnh gọi: single, proxy, browser, hoặc api
retryAfter number Thời gian chờ khuyến nghị tính bằng giây trước khi thử lại
current.concurrency number Số request dịch vụ đang xử lý trên tất cả khách hàng khi từ chối
current.rpm number Số request dịch vụ đã tiếp nhận trên tất cả khách hàng trong 60 giây qua
limits.maxConcurrency number Hạn mức đồng thời dùng chung của dịch vụ
limits.maxRpm number Hạn mức mỗi phút dùng chung của dịch vụ

Xử lý mọi từ chối bằng một helper

Retry-After được thiết lập trên các giới hạn gói cước đáng để chờ đợi, retry_after_seconds nằm trong body của chúng, và retryAfter nằm trong body của nền tảng. Đọc cả ba theo thứ tự đó, và dừng lại ở các giới hạn gói cước mà việc chờ đợi không thể giải quyết:

import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

def fetch(url, api_key, max_retries=5):
    for attempt in range(max_retries):
        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},
        )

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")

Hạn mức theo ngày không thể hồi phục sau vài giờ, và hạn mức theo chu kỳ không thể hồi phục sau vài ngày, vì vậy hãy coi chúng là một lệnh dừng hẳn thay vì tạm chờ. Đọc resets_at từ body nếu bạn muốn lên lịch cho lần chạy tiếp theo.

Mẹo

  • Giới hạn số lượng request đang xử lý (in flight) thay vì thử lại toàn bộ đợt bị từ chối. Một đợt bão retry sẽ biến một lỗi 429 thành nhiều lỗi liên tiếp.
  • Đọc X-FourA-Limit trước. Giá trị này cho bạn biết qua một chuỗi duy nhất liệu giới hạn thuộc về bạn hay từ nền tảng, và không có trường hợp từ chối nào từ nền tảng thiết lập trường này.
  • Không hardcode các con số. Mọi response chạm giới hạn gói cước đều chứa mức trần đã từ chối nó, và mục Sử dụng & Giới hạn sẽ hiển thị toàn bộ các thông số đó.
  • retryAfter trên các giới hạn nền tảng được cố định theo từng loại: 2 giây cho concurrency, 5 giây cho RPM, 60 giây cho bảo trì.
  • Khớp theo error để phân biệt hai loại lỗi 503. Cả hai định dạng đều chứa current và limits, do đó bước kiểm tra "các trường đó có tồn tại không?" sẽ hiểu nhầm việc bảo trì thành sự cố concurrency.
  • Mã 403 đi kèm X-FourA-Limit liên quan đến gói cước của bạn, không liên quan đến trang web mục tiêu. Trang web mục tiêu chưa từng phản hồi.

Cổng Proxy có các thông số riêng

Mọi thông tin phía trên đều áp dụng cho JSON API. Lưu lượng truy cập bạn gửi qua proxy.foura.ai được áp dụng một bộ thông số gói riêng biệt, theo đơn vị khác: số tunnel mở cùng lúc, số tunnel mở mỗi phút, và lưu lượng tiêu chuẩn cho chu kỳ thanh toán. Các phản hồi từ chối đó xuất hiện dưới dạng một HTTP status kèm header X-Foura-Error thay vì JSON body, vì lệnh CONNECT không có phần body để chứa thông tin. Xem Cổng Proxy để biết bảng trạng thái và Cách tính lưu lượng gói cước để biết gigabyte của cổng proxy được trừ vào nhóm tài nguyên nào.

Cập nhật: 6 tháng 11, 2026