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 theo API key¶

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

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¶

TikTok tính giới hạn theo app_id, không theo từng khách. 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.

Circuit breaker 5 phút

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.

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

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

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 trong bucket của key
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.

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

TikTok 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ế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.

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

import httpx, time

def get(path, params, key, account_id):
    while True:
        r = httpx.get(f"https://api.logidata.vn/v1/tiktok-ads{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()