Giới hạn tần suất

Yêu cầu API bị giới hạn theo khóa API và theo nhóm endpoint:

Endpoint	Giới hạn
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 yêu cầu / phút cho mỗi API key (120 / phút cho mỗi IP)
POST /v1/detect · POST /v1/detect/file	10 yêu cầu / phút cho mỗi API key (30 / phút cho mỗi IP)
POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket theo API key: burst 60, nạp lại 1/giây (≈60 / phút duy trì); theo tài khoản: burst 120, nạp lại 2/giây. Lớp IP cho phép 180 / phút. Mỗi phản hồi đều có header X-RateLimit-Remaining.

Tiêu đề phản hồi

Các tiêu đề bạn nhận được phụ thuộc vào lớp nào đã trả lời, và ba nhóm không hành xử giống nhau:

Tiêu đề	Ý nghĩa	Khi nào xuất hiện
X-RateLimit-Remaining	Số yêu cầu (hoặc token) còn lại trong cửa sổ hiện tại	Mọi phản hồi ở cả ba nhóm
X-RateLimit-Limit	Mức trần đã áp dụng	Mọi phản hồi chung và phản hồi phát hiện, cùng mọi 429 từ lớp IP. Không bao giờ có trong phản hồi thời gian thực — thời gian thực tiêu thụ nhóm token nên không có mức trần cố định
Retry-After	Số giây cần đợi trước khi thử lại	Chỉ khi gặp 429
X-RateLimit-Reset	Dấu thời gian Unix khi cửa sổ đặt lại	Chỉ khi 429 thuộc nhóm chung hoặc nhóm phát hiện; không bao giờ từ thời gian thực hay lớp IP

X-RateLimit-Remaining là tiêu đề duy nhất bạn có thể tin cậy vô điều kiện, và cũng là tiêu đề duy nhất mà thời gian thực trả về khi thành công.

Khi bạn gặp 429

Khi vượt giới hạn, API trả về 429 kèm header Retry-After (phản hồi realtime còn có trường retry_after). Tạm dừng theo số giây được báo rồi tiếp tục với exponential backoff.

{
  "message": "Too many requests. Limit: 60/min."
}

Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0