Giới hạn tần suất & hạn mức¶

Có ba tầng giới hạn. Biết trước cả ba sẽ tiết kiệm cho bạn một buổi debug.

1. Tần suất của tài khoản¶

Token bucket, tính theo giây, có cho phép dồn cục ngắn (burst = 2× rps).

Gói	Tần suất
Dùng thử / Starter	2 req/giây
Growth	5 req/giây
Business	10 req/giây
Enterprise	tuỳ chỉnh

Con số này là trần của cả tài khoản, không phải của từng API key: mọi key của bạn — cộng cả MCP và trang chạy thử trên portal — rút chung một bucket. Tạo thêm key không được thêm tần suất. Mỗi key còn có bucket riêng của nó, mặc định bằng đúng mức trên, nên tách key theo từng dịch vụ vẫn hữu ích để một job chạy loạn không nuốt trọn phần của job khác.

Vượt → 429 rate_limited kèm Retry-After: 1. Request bị chặn ở đây không tính vào hạn mức tháng.

2. Trần dùng chung của ứng dụng¶

Một số nền tảng tính giới hạn theo app developer, không theo từng khách — TikTok là ví dụ rõ nhất. Nghĩa là toàn bộ khách của Logidata dùng chung một trần. Logidata giữ mức sử dụng ở 80% trần để không ai làm cả hệ thống chết.

Chạm trần → 429 upstream_rate_limited. Hiếm gặp, và thường tự hết trong vài giây.

Trần này khác nhau theo nền tảng:

Nền tảng	Cơ chế trần của nền tảng
`tiktok-ads`, `tiktok-shop`	Theo app developer — dùng chung, phạt nặng khi vượt
`shopee`, `shopee-ads`	Theo partner app, cộng thêm giới hạn theo shop
`google-ads`	Không có trần dùng chung theo app ⇒ dễ mở rộng nhất cho khối lượng lớn

Circuit breaker 5 phút (TikTok Ads)

Nếu TikTok trả 40100 (vượt QPM cấp ứng dụng), Logidata dừng nhận request cho toàn bộ nền tảng đó trong 5 phút và trả 429 upstream_rate_limited kèm Retry-After: 300.

Đây là cố ý. TikTok phạt cả ứng dụng khi bị vượt, nên gọi tiếp trong lúc bị phạt chỉ kéo dài thời gian phạt cho tất cả mọi người. Hãy tôn trọng Retry-After — đừng retry ngay.

Với Google Ads thì ngược lại: khi Google báo giới hạn, retry có backoff là hành vi đúng, và Logidata làm việc đó hộ bạn.

3. Hạn mức tháng¶

Đếm theo số request, không theo số dòng dữ liệu. Reset đầu tháng dương lịch (giờ UTC).

Gói	Request/tháng
Dùng thử	2.000
Starter	5.000
Growth	100.000
Business	500.000
Enterprise	tuỳ chỉnh

Hết hạn mức có thể mua thêm block request thay vì chờ nâng gói.

Hết hạn mức → 429 quota_exceeded.

Hạn mức tính chung cho cả tài khoản, không tách theo từng API key: tạo thêm key không được thêm hạn mức. X-Quota-Remaining và /v1/me vì thế trả về số của cả tài khoản.

Không tính vào hạn mức: request bị chặn bởi tần suất (tầng 1 & 2), lỗi 502 upstream_unreachable, và endpoint /v1/me.

Header trên mỗi response¶

X-RateLimit-Remaining: 3      # token còn lại — mức chặt hơn giữa bucket key và tài khoản
X-Quota-Limit: 2000           # hạn mức tháng
X-Quota-Remaining: 1847       # còn lại trong tháng
X-Request-Id: 6f1c2f0e-…      # gửi kèm khi báo lỗi cho Logidata

Cách kéo dữ liệu cho hiệu quả¶

Tăng page_size thay vì tăng số request

page_size=1000 lấy được cùng lượng dữ liệu với 1 request thay vì 100. Hạn mức tính theo request, nên đây là cách rẻ nhất để tiết kiệm.

Gom nhiều ngày vào một lần gọi

report/integrated/get/ nhận khoảng start_date–end_date và trả về theo ngày qua dimension stat_time_day. Một request cho cả tuần rẻ hơn 7 request cho từng ngày.

Cache dữ liệu ít thay đổi

Tên campaign/adgroup/ad và thông tin advertiser gần như không đổi. Kéo một lần mỗi ngày là đủ; đừng gọi lại trong mỗi vòng lặp báo cáo.

Cache của Logidata không tính vào hạn mức

Với các endpoint gọi lặp lại rất nhiều trên cùng một bản ghi — điển hình là đối soát Shopee, một request cho mỗi đơn — Logidata cache kết quả và cache hit không bị tính. Cùng lượng dữ liệu, số request tính tiền giảm khoảng 7 lần so với tự gọi thẳng nền tảng.

Số liệu hôm nay chưa chốt

Các nền tảng cập nhật dần trong ngày và có thể điều chỉnh số liệu tới 48 giờ sau; đơn hàng còn đổi trạng thái và phát sinh hoàn trả nhiều ngày sau. Nếu bạn cần con số ổn định, kéo lại dữ liệu 2–3 ngày gần nhất mỗi lần chạy.

Không muốn tự quản lý việc này?

Toàn bộ mục trên — phân trang, cửa sổ kéo lại, tôn trọng Retry-After, thử lại khi lỗi — là thứ đồng bộ tự động làm sẵn, và nó chạy trên hạ tầng Logidata nên không tiêu hạn mức API key của bạn.

Ví dụ: tôn trọng `Retry-After`¶

import httpx, time

def get(provider, path, params, key, account_id):
    while True:
        r = httpx.get(f"https://api.logidata.vn/v1/{provider}{path}",
                      params=params, timeout=60,
                      headers={"X-API-Key": key, "X-Account-Id": account_id})
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 1))
            print(f"bị giới hạn, chờ {wait}s")
            time.sleep(wait)      # circuit breaker có thể là 300s — cứ chờ
            continue
        r.raise_for_status()
        return r.json()