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

Tổng quan

TTS Open Platform sử dụng cơ chế Dynamic QPS Allocation (Phân bổ QPS động): hạn mức QPS của app được tính toán động dựa trên quy mô shop được ủy quyền × đặc tính tài nguyên API. Càng nhiều shop được ủy quyền, hạn mức của bạn càng cao.
Nền tảng không cung cấp một giá trị QPS cố định để truy vấn. Hãy xây dựng một client tự thích ứng, tự điều tiết tần suất dựa trên các phản hồi 429, kết hợp với exponential backoff + jitter + batch API + caching.
Nhận được 429 không nhất thiết có nghĩa là app của bạn đã vượt giới hạn tần suất — đó cũng có thể là biện pháp điều tiết bảo vệ ở cấp nền tảng đối với API. Chiến lược xử lý là như nhau: lùi lại và thử lại.

1. Tại sao tồn tại giới hạn tần suất API

Giới hạn tần suất API là cơ chế nền tảng giúp giữ cho hệ thống ổn định và công bằng. Nó phục vụ hai mục tiêu:

Ổn định nền tảng — ngăn các đợt tăng đột biến lưu lượng làm quá tải dịch vụ và làm giảm chất lượng truy cập của tất cả mọi người.
Phân bổ tài nguyên công bằng — phân phối năng lực nền tảng một cách công bằng giữa các developer, để một số ít app không thể độc chiếm tài nguyên gây thiệt hại cho những app khác.

Chúng tôi đặc biệt khuyến nghị mọi developer áp dụng các mẫu throttling, caching và retry theo tiêu chuẩn ngành để xây dựng các ứng dụng có khả năng phục hồi.

2. Phân bổ QPS động

2.1 Hai chiều của việc tính hạn mức

Thay vì một hạn mức cố định áp dụng chung cho tất cả, nền tảng tính trần QPS cho mỗi app một cách động theo hai chiều:

Dimension	Effect on Your Quota
App Authorization Scale(số shop được ủy quyền)	Số shop được ủy quyền là cơ sở cho hạn mức của bạn. App của bạn được ủy quyền cho càng nhiều shop, tổng QPS được phân bổ càng cao. Nếu bạn dự đoán doanh nghiệp tăng trưởng và cần QPS cao hơn, con đường trực tiếp nhất là mở rộng quy mô ủy quyền shop — không cần đăng ký riêng.
API Resource Characteristics(phân tầng theo từng endpoint)	Mỗi API được xếp hạng theo bản chất đọc/ghi, tải nhẹ so với tải nặng, và tải nền tảng thời gian thực:

API đọc nhẹ (ví dụ tra cứu thông tin sản phẩm) → hạn mức tương đối cao hơn
API tải nặng hoặc API ghi (ví dụ tạo đơn hàng, phân tích phức tạp) → hạn mức tương đối thấp hơnTrần cho bất kỳ API đơn lẻ nào được điều chỉnh động dựa trên điều kiện nền tảng. |

2.2 Đơn vị cô lập giới hạn tần suất

Đơn vị cô lập tối thiểu cho giới hạn tần suất là tổ hợp App ID × Authorized Shop:

Cùng một shop được ủy quyền cho các app khác nhau → hạn mức độc lập giữa các app.
Cùng một app được ủy quyền cho nhiều shop → hạn mức độc lập giữa các shop.

Hạn mức QPS của mỗi đơn vị cô lập được tính động theo §2.1; không có giá trị cố định thống nhất.

Mẹo triển khai: Không hard-code một ngưỡng QPS trong code của bạn. Xây dựng một client thích ứng với các phản hồi 429 là cách bền vững hơn nhiều so với việc gắn cứng một giá trị tĩnh.

3. Mã phản hồi & cách xử lý khi bị điều tiết

Phân biệt chính xác 429 với 503 là điều kiện tiên quyết cho một client bền vững. Hai mã này có nguyên nhân gốc khác nhau và hành động khác nhau:

HTTP Status	Root Cause & Action
429 Too Many Requests(Bị giới hạn tần suất)	Hai nguyên nhân gốc có thể xảy ra:

App của bạn đã vượt quá QPS được phân bổ động trong đơn vị cô lập hiện tại.
API gặp biện pháp điều tiết bảo vệ ở cấp nền tảng (độc lập với tần suất request của app bạn).Cả hai trường hợp đều có chung cách xử lý:
Dừng gửi request mới ngay lập tức.
Thử lại bằng exponential backoff + random jitter (xem §4.5).
⛔ Không bao giờ thử lại ngay lập tức với tần suất cao — điều đó sẽ làm tình trạng điều tiết tệ hơn và có thể kéo dài thời gian hạn chế. | | 503 Service Unavailable | Không phải là giới hạn tần suất. Nó cho biết dịch vụ bên dưới đang quá tải, gặp lỗi tạm thời, hoặc đang bảo trì.
Thường là tạm thời — thử lại sau một khoảng chờ ngắn.
Nếu tình trạng kéo dài, hãy kiểm tra trang thông báo dành cho developer hoặc liên hệ hỗ trợ kỹ thuật để xác minh xem có sự cố đã biết nào đang diễn ra hay không. |

4. Thực hành tốt nhất (5 mục, sắp xếp theo mức độ ưu tiên)

1. Sử dụng Batch API (ưu tiên hàng đầu)Nền tảng cung cấp batch endpoint cho nhiều tình huống. Bất cứ nơi nào có batch endpoint, đừng lặp endpoint đơn lẻ — gộp N lần gọi thành một là cách hiệu quả nhất để giữ dưới giới hạn tần suất.

2. Hàng đợi request & throttlingDuy trì một hàng đợi request nội bộ và điều phối ở tốc độ mượt mà, có kiểm soát. Tránh các đợt bùng nổ khi nhiều request được gửi trong cùng một giây.

3. Chỉ lấy những gì bạn cầnCắt giảm request API xuống mức tối thiểu các trường và khối lượng mà nghiệp vụ của bạn thực sự cần. Tránh kéo toàn bộ dữ liệu khi một lần đồng bộ tăng dần (incremental sync) là đủ.

4. Cache dữ liệu nóngCache dữ liệu ít thay đổi, đọc nhiều (ví dụ dữ liệu gốc sản phẩm, cấu hình shop, ánh xạ category) ở phía bạn. Điều này giảm đáng kể lưu lượng API không cần thiết.

5. Idempotency + xử lý lỗi phân tầng

Làm cho mọi thao tác ghi (create/update) có tính idempotent để các lần thử lại không thể tạo ra dữ liệu trùng lặp hoặc dữ liệu bẩn.
Phân biệt 429 / 503 / lỗi nghiệp vụ / lỗi mạng và áp dụng cách phản hồi phù hợp cho từng loại.

4.5 Exponential Backoff + Random Jitter (trình xử lý `429` tiêu chuẩn)

Khi bạn nhận được 429, bạn phải thử lại bằng Exponential Backoff + Jitter:

PLAINWord Wrap

wait = base_delay * (2 ** retry_count) + random_jitter

Các tham số quan trọng:

base_delay — bắt đầu ở 1 giây.
Nhân đôi thời gian chờ sau mỗi lần thất bại (1s → 2s → 4s → 8s …) và giới hạn nó (ví dụ 60s).
random_jitter — thêm một độ lệch ngẫu nhiên nhỏ (ví dụ 0–500ms) lên trên thời gian chờ để ngăn nhiều instance đồng bộ hóa các lần thử lại của chúng và tạo ra một đợt tăng đột biến mới.
Đặt số lần thử lại tối đa (ví dụ 5). Vượt quá mức đó, hãy đưa ra cảnh báo hoặc chuyển sang phương án dự phòng suy giảm.

Triển khai tham khảo bằng Python:

PYTHONWord Wrap

import random, time  
  
def backoff_sleep(retry: int, base: float = 1.0, cap: float = 60.0):  
    wait = min(base * (2 ** retry) + random.uniform(0, 0.5), cap)  
    time.sleep(wait)

5. FAQ

Q1: Làm sao tôi biết chính xác app của mình nhận được bao nhiêu hạn mức QPS?

A: Hạn mức được tính động. Nền tảng không cung cấp API truy vấn hạn mức cố định. Cách tiếp cận đúng là làm cho app của bạn tự thích ứng: phản ứng với các phản hồi 429 để điều tiết động, thay vì dựa vào một ngưỡng hard-code.

Q2: Doanh nghiệp của tôi đang tăng trưởng nhanh. Làm sao tôi tăng hạn mức QPS?

A: Ý tưởng cốt lõi của cơ chế phân bổ động là hạn mức của bạn tự động tăng theo quy mô shop được ủy quyền. Con đường trực tiếp nhất và được khuyến nghị là:

Mở rộng quy mô ủy quyền shop — app của bạn được ủy quyền cho càng nhiều shop, tổng QPS mà nền tảng phân bổ càng cao. Không cần đăng ký riêng.
Đối với các đợt khuyến mãi lớn hoặc các sự kiện cao điểm đặc biệt, nếu bạn đã triển khai mọi thực hành tốt nhất mà vẫn dự đoán sẽ gặp điểm nghẽn, hãy liên hệ Account Manager (AM) của bạn hoặc hỗ trợ kỹ thuật của nền tảng trước để cùng đánh giá các phương án.

Q3: Tôi hiếm khi gửi request — tại sao thỉnh thoảng vẫn thấy 429?

A: Có ba nguyên nhân phổ biến:

Bùng nổ trong dưới một giây: ngay cả khi QPS tổng thể thấp, việc gửi vài request trong cùng một giây có thể kích hoạt điều tiết. Hãy dùng một hàng đợi request để điều phối mượt mà.
Điều tiết bảo vệ ở cấp nền tảng đối với API: trong các trường hợp hiếm, khi tải toàn nền tảng của một API đạt ngưỡng bảo vệ, nền tảng tạm thời giảm hạn mức khả dụng cho tất cả các bên gọi. Điều này độc lập với tần suất request của app bạn, và cách xử lý là như nhau — lùi lại và thử lại theo §4.5.
Cạnh tranh đồng thời trong cùng một đơn vị cô lập: mặc dù giới hạn tần suất được phân phạm vi theo App × Shop, nhiều instance của app bạn vẫn có thể chồng chất request trong các khoảng thời gian mili-giây.

Q4: QPS được tính như thế nào cho batch endpoint so với single-item endpoint?

A: Batch endpoint thường được tính là một lần gọi cho mỗi request (không phải mỗi item trong batch). Bất cứ khi nào có batch endpoint, hãy ưu tiên dùng nó. Tham khảo tài liệu của từng endpoint để biết quy tắc tính chính xác của nó.