# Rate Limit

> URL: https://foura.ai/vi/docs/api/rate-limits
> Updated: 2026-11-06
> Index: https://foura.ai/llms.txt

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](#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](https://foura.ai/docs/api/endpoints#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](https://foura.ai/docs/dashboard/quota) 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.

```json
{
  "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ố:

```json
{
  "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](https://foura.ai/docs/api/endpoints#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`:

```json
{
  "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](https://foura.ai/docs/how-to/run-requests-in-parallel) để 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ộ.

```json
{
  "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:

```json
{
  "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](https://foura.ai/docs/api/response-headers).

```json
{
  "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.

```json
{
  "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ụ.

```json
{
  "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](https://foura.ai/docs/api/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](https://foura.ai/dashboard).

### 429: Vượt quá RPM

```json
{
  "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

```json
{
  "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:

```json
{
  "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:

```python
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](https://foura.ai/docs/dashboard/quota) 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](https://foura.ai/docs/api/proxy-port#responses) để biết bảng trạng thái và [Cách tính lưu lượng gói cước](https://foura.ai/docs/guides/plans-and-metering) để biết gigabyte của cổng proxy được trừ vào nhóm tài nguyên nào.

## Liên quan

- [Chạy request song song](https://foura.ai/docs/how-to/run-requests-in-parallel): Mô hình bounded-concurrency mẫu kèm hướng dẫn
- [Sử dụng & Giới hạn](https://foura.ai/docs/dashboard/quota): Mọi giới hạn của gói cước bên cạnh mức sử dụng trực tiếp của bạn
- [API Endpoint](https://foura.ai/docs/api/endpoints): Tài liệu tham khảo tham số đầy đủ
- [Xử lý lỗi](https://foura.ai/docs/api/errors): Tất cả các loại lỗi và response
- [Response Header](https://foura.ai/docs/api/response-headers): `X-FourA-Limit`, `Retry-After`, và các header khác
- [Khắc phục sự cố](https://foura.ai/docs/troubleshooting/common-issues): Các sự cố thường gặp và cách xử lý
