> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madiad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limit

> Số request tối đa mỗi phút bạn có thể gọi, và điều gì xảy ra khi vượt quá.

MADIAD Hub áp dụng rate limit theo từng khách hàng. Vì đăng bài không giới hạn trên mọi gói trả phí, với một lệnh đăng thì rate limit là thứ duy nhất bạn có thể chạm phải:

* **Rate limit** là tốc độ bạn có thể gọi API, được kiểm tra trên mọi request đã xác thực.
* **Các hạn mức còn lại** gồm phút FFmpeg, số Profile và số DM mỗi ngày vẫn giới hạn theo gói; riêng số bài đăng thì không. Xem [Mức sử dụng](/vi/concepts/usage) để biết số liệu hiện tại.

Hai loại giới hạn này độc lập với nhau, bạn có thể còn nguyên hạn mức FFmpeg nhưng vẫn bị rate limit vì gửi quá nhiều request trong thời gian ngắn.

## Giới hạn cụ thể

* **Cửa sổ cố định 60 giây**, tính theo từng tài khoản khách hàng (không tính theo từng API key hay từng profile).
* **Mặc định 120 request/phút.** Đây là mức tiêu chuẩn, không phải giới hạn tuyệt đối. MADIAD Hub có thể nâng trần này cho tích hợp có lưu lượng lớn, liên hệ hỗ trợ nếu bạn cần cao hơn.
* Đây là **cửa sổ cố định**: bộ đếm được reset ở mỗi mốc 60 giây, nên lượng dùng không cộng dồn sang cửa sổ kế tiếp.

## Khi vượt giới hạn

API trả về:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (120/min). Slow down and retry shortly."
  }
}
```

Xem [Lỗi](/vi/concepts/errors) để biết đầy đủ bảng mã lỗi.

## Xử lý lỗi 429

* **Tuân theo `Retry-After`.** Header này cho biết chính xác cần chờ bao nhiêu giây trước khi thử lại, đừng gửi lại sớm hơn.
* **Backoff theo cấp số nhân** nếu bạn gọi API trong vòng lặp hoặc từ một worker xử lý hàng đợi và liên tục gặp 429, thay vì dồn dập gửi request mỗi khi cửa sổ reset.
* **Giãn cách các đợt gửi liên tiếp.** Nếu bạn đang tạo nhiều bài đăng cùng lúc (ví dụ lên lịch hàng loạt từ một script), hãy thêm một khoảng trễ nhỏ giữa các request thay vì thực hiện đồng thời tất cả.

<Tip>
  Nếu một request tạo dữ liệu mới (như đăng bài) bị rate limit và bạn thử lại, hãy gửi cùng `Idempotency-Key` đã dùng ở lần đầu, xem [Idempotency](/vi/concepts/idempotency). Nhờ vậy, thao tác đó sẽ không bao giờ sinh ra bài đăng trùng lặp.
</Tip>

## Khi bản thân rate limiter gặp sự cố

Rate limiter được thiết kế để ưu tiên cho phép truy cập khi gặp sự cố: nếu việc kiểm tra bên dưới gặp lỗi vì bất kỳ lý do gì, MADIAD Hub vẫn cho request đi qua thay vì chặn lại. Sự cố ở phía rate limiter sẽ không bao giờ là lý do khiến lưu lượng hợp lệ của bạn bị chặn.