Lịch sử: Rate limit

Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.

02/10/2026 · +1 −1 dòng

Xem thay đổi

⋯
  3. Nếu lưu lượng **bình thường** của bạn chạm ngưỡng, hãy hỏi trong kênh Discord Wandura của team bạn để nâng ngưỡng cho tổ chức. Ngưỡng mới có hiệu lực trong khoảng một phút.
  
- > **Đang triển khai.** Wandura nhận cảnh báo, trong một kênh riêng, khi tổ chức của bạn chạm ngưỡng playback.
+ Wandura theo dõi các tổ chức chạm ngưỡng playback. Bạn vẫn nên báo Wandura trong kênh của bạn khi lưu lượng bình thường chạm ngưỡng: đó là cách để được nâng ngưỡng.
  
  Luật retry cho mọi response: [chính sách retry](../reference/behaviour.md#retries).
⋯

02/10/2026 · +36 −44 dòng

Xem thay đổi

  # Rate limit
  
- Delivery API áp một ngưỡng chống lạm dụng cho mỗi tổ chức. Ngưỡng này được đặt cao hơn rất nhiều so với lưu lượng của một tích hợp bình thường, nên chạm ngưỡng thường có nghĩa là có vòng lặp chạy mất kiểm soát hoặc một cơn bão retry. Trang này giải thích cách đếm, API trả về gì khi bạn chạm ngưỡng và cách khôi phục.
- 
- ## Cách đếm request
- 
- - **Theo tổ chức.** Request được đếm chung cho cả tổ chức, không theo từng key. Tạo thêm key không nâng ngưỡng của bạn.
- - **Theo nhóm endpoint.** Playback, catalog và creatives mỗi nhóm có bộ đếm riêng, nên một vòng đồng bộ creatives chạy mất kiểm soát không chặn được catalog của bạn.
- - **Nạp lại từng giây.** Playback và catalog nạp lại hạn mức liên tục, mỗi giây một phần sáu mươi ngưỡng. Endpoint creatives dùng cửa sổ cố định, reset khi mỗi cửa sổ bắt đầu.
- - **Chỉ request đã xác thực.** Request thiếu key hoặc key không hợp lệ bị từ chối trước khi được đếm, nên không ai khác làm cạn ngưỡng của bạn được.
+ > **TL;DR** — Mỗi tổ chức có một ngưỡng chống lạm dụng cho từng bộ đếm endpoint, cao hơn rất nhiều so với lưu lượng bình thường. Playback đếm **vé**, không đếm request, và nạp lại từng giây. Khi gần chạm ngưỡng, Wandura chậm lại thay vì lỗi: prefetch bị từ chối trước, request `play` có thể chờ nửa giây, và request lặp lại nhận lại vé đã cấp. Gặp `429` thì chờ hết `Retry-After`. Các con số: [Hành vi chuẩn của API · Rate limit](../reference/behaviour.md#rate-limits).
  
- Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`. Request được trả bằng một vé Wandura đã cấp trước đó (xem [Quá tải nhẹ nhàng](#graceful-overload)) không bị tính, và request bị từ chối không tiêu hạn mức của bạn.
+ ## Cách đếm {#how-requests-are-counted}
  
- ## Ngưỡng hiện tại {#limits}
+ - **Theo tổ chức**, không theo từng key: thêm key không nâng ngưỡng.
+ - **Theo bộ đếm**: playback, catalog, creatives, danh sách video mở, một video mở và cấu hình mỗi thứ có bộ đếm riêng, nên một job chạy mất kiểm soát ở chỗ này không chặn được chỗ khác.
+ - **Theo đơn vị của bộ đếm**: playback đếm vé (một lô 3 vé tính 3; vé dùng lại tính 0; vé bị từ chối tính 0); các bộ đếm khác đếm request.
+ - **Chỉ key hợp lệ** mới được đếm: không ai thiếu key của bạn mà làm cạn ngưỡng của bạn được. Nhưng ai điều khiển được endpoint xin vé **của bạn** thì làm được: hãy giới hạn số vé theo người xem ở phía bạn ([Bảo mật](security.md#trust-boundary)).
  
- | Nhóm endpoint | Ngưỡng mỗi tổ chức | Cửa sổ |
- |---|---|---|
- | Playback: `POST /api/delivery/v1/playback` | 10.800 request (khoảng 180 vé mỗi giây) | 60 giây |
- | Catalog: `GET /api/delivery/v1/catalog` | 3.000 request | 60 giây |
- | Creatives: `GET /api/delivery/v1/creatives`, `GET /api/delivery/v1/creatives/{id}` (một bộ đếm cho cả hai) | 3.000 request | 60 giây |
+ Ngưỡng của từng bộ đếm, kèm đơn vị, nằm chung một bảng: [Hành vi chuẩn của API · Rate limit](../reference/behaviour.md#rate-limits). `GET /config` trả về các ngưỡng đang áp cho tổ chức của bạn.
  
- Playback và catalog không có mốc phút: hạn mức được nạp lại từng giây (xem [Quá tải nhẹ nhàng](#graceful-overload)). Bộ đếm creatives dùng cửa sổ một phút đồng hồ (UTC), nên bắt đầu lại ở mỗi phút tròn. Một người xem bắt đầu một tập thường tốn khoảng ba vé playback (chính tập đó cộng các vé xin trước), nên ngưỡng playback tương đương khoảng 60 người bắt đầu xem mỗi giây.
+ ## Nạp lại {#refill}
  
- Bộ đếm chỉ xấp xỉ về phía cao: server của Wandura đếm theo lô nhỏ, nên một đợt dồn có thể lọt vài request quá ngưỡng (tối đa khoảng 2,5 % với lưu lượng bình thường) trước khi `429` bắt đầu.
+ | Bộ đếm | Hạn mức quay lại thế nào |
+ |---|---|
+ | `playback`, `catalog` | **Liên tục**: mỗi giây một phần sáu mươi ngưỡng. Từ lúc rảnh, bạn dùng được nguyên hạn mức của một phút cùng lúc; sau đó chỗ trống quay lại từng giây, nên `Retry-After` thường là **1–2 giây**. |
+ | `creatives`, `videos`, `video`, `config` | **Theo phút đồng hồ (UTC)**: bộ đếm bắt đầu lại ở mỗi phút tròn; `Retry-After` là phần còn lại của phút. |
  
- Wandura nâng được bất kỳ ngưỡng nào ở trên riêng cho tổ chức của bạn: hỏi trong kênh Discord Wandura của team bạn. Ngưỡng mới có hiệu lực trong khoảng một phút, bạn không phải đổi gì. Wandura cũng nhận cảnh báo khi một tổ chức chạm ngưỡng playback. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
+ Bộ đếm chỉ xấp xỉ về phía cao: một đợt dồn có thể vượt ngưỡng tới khoảng 2,5 % trước khi `429` bắt đầu.
  
  ## Quá tải nhẹ nhàng {#graceful-overload}
  
- Khi gần và vượt ngưỡng, Wandura chậm lại thay vì lỗi, và ưu tiên tập người xem vừa chạm vào:
+ Khi gần chạm ngưỡng playback, Wandura bảo vệ tập người xem vừa chạm vào:
  
  | Tình huống | Điều xảy ra |
  |---|---|
- | Bạn dùng hết hạn mức playback | Hạn mức được **nạp lại từng giây** (ngưỡng chia 60), thay vì mỗi phút một lần. `Retry-After` cho biết bao lâu nữa có chỗ, thường **1–2 giây**. Từ lúc rảnh, bạn vẫn gửi được nguyên ngưỡng của một phút cùng lúc. |
- | Lưu lượng playback của bạn gần chạm ngưỡng | **Prefetch bị tạm dừng trước.** Khi còn dưới khoảng 20 % hạn mức, request có `"intent": "prefetch"` nhận `429` `rate_limited` kèm `"reason": "prefetch_shed"`, trong khi request cho tập người xem vừa chạm (`"intent": "play"`, hoặc không có `intent`) vẫn được cấp vé. |
- | Một lô có nhiều phần tử hơn chỗ còn lại | Phần tử prefetch bị từ chối trước. Phần tử nào không cấp được nhận `"status": 429` và `retry_after` riêng (kèm `"reason": "prefetch_shed"` nếu là prefetch bị tạm dừng), các phần tử còn lại vẫn nhận vé. Cả request chỉ trả `429` khi không phần tử nào cấp được. |
- | Request `play` tới sớm hơn lúc có chỗ vài trăm mili giây | Wandura **giữ request tối đa khoảng 0,5 giây** rồi cấp vé, thay vì trả `429`. Hãy để timeout phía client ít nhất 5 giây. Request prefetch không bao giờ bị giữ. |
- | Cùng người xem xin lại cùng một tập | Nếu bạn gửi `viewer_ref`, request lặp lại với cùng `viewer_ref`, tập, intent và giá trị thiết bị, trong lúc vé trước còn ít nhất 5 phút, nhận lại **đúng vé đó** (cùng `expires_at`, không gia hạn). Request đó không bị tính vào ngưỡng. Xem [Playback](playback.md#viewer-ref). |
+ | Còn dưới khoảng 20 % hạn mức playback | Request có `"intent": "prefetch"` nhận `429` `rate_limited` kèm `"reason": "prefetch_shed"`. Request `play` vẫn được cấp vé. |
+ | Một lô có nhiều phần tử hơn chỗ còn lại | Phần tử prefetch bị từ chối trước, mỗi phần tử có `429` và `retry_after` riêng; các phần tử còn lại nhận vé. Cả request chỉ trả `429` khi không phần tử nào cấp được. |
+ | Request `play` tới sớm hơn lúc có chỗ vài trăm mili giây | Wandura giữ request tối đa khoảng **0,5 giây**, rồi cấp vé. Hãy để timeout phía client ít nhất 5 giây. Prefetch không bao giờ bị giữ. |
+ | Cùng người xem xin lại cùng tập trên cùng thiết bị | Vé đã cấp được trả lại, không bị tính (cần `viewer_ref`; xem [Playback](playback.md#viewer-ref)). |
  
  Prefetch bị tạm dừng trả về:
⋯
  ```
  
- Xử lý như mọi `429`: đây không phải lỗi với người xem. Xin lại tập đó với `"intent": "play"` khi người xem chạm vào. Ngưỡng catalog cũng được nạp lại từng giây như vậy; request catalog không bao giờ bị giữ.
+ Đây không phải lỗi với người xem: xin tập đó với `"intent": "play"` khi người xem chạm vào.
  
- ## Khi bạn chạm ngưỡng
+ ## Khi chạm ngưỡng {#when-you-reach-the-ceiling}
  
- Mọi endpoint, kể cả endpoint creatives, đều trả `429 Too Many Requests` với body lỗi phẳng:
+ Mọi endpoint trả `429` với body phẳng, kể cả các endpoint creatives:
  
  ```json
  {
-   "error": "Too many playback requests for this account. This is an abuse ceiling, not a quota — if a normal integration reaches it, contact us and it will be raised.",
+   "error": "Too many catalog requests for this account. This is an abuse ceiling, not a quota — if a normal integration reaches it, contact us and it will be raised.",
    "error_code": "rate_limited"
  }
  ```
  
- Response kèm các header sau:
- 
- | Header | Mô tả |
+ | Header (chỉ có ở `429`) | Ý nghĩa |
  |---|---|
- | `Retry-After` | Số giây cho đến khi hạn mức nạp lại đủ, thường 1–2. Ở endpoint creatives, số giây cho đến khi cửa sổ hiện tại reset. |
- | `X-RateLimit-Limit` | Số request được phép trong mỗi cửa sổ cho nhóm endpoint này. |
- | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. |
+ | `Retry-After` | Số giây cho tới khi có chỗ trở lại. |
+ | `X-RateLimit-Limit` | Ngưỡng của bộ đếm này cho tổ chức của bạn, trên mỗi cửa sổ (playback: tính bằng vé). |
+ | `X-RateLimit-Window` | Cửa sổ, tính bằng giây (60). |
  
- Các header giới hạn chỉ xuất hiện trên response `429`.
+ ## Cách khôi phục {#how-to-recover}
  
- ## Cách khôi phục
+ 1. Ngừng gửi tới bộ đếm đó cho tới khi hết `Retry-After`, cộng thêm ngẫu nhiên 0–1 giây (jitter). Retry sớm hơn chỉ nhận thêm `429`.
+ 2. Tìm nguyên nhân: vòng retry không có backoff, job xin vé cho cả catalog, gọi catalog mỗi lần mở app.
+ 3. Nếu lưu lượng **bình thường** của bạn chạm ngưỡng, hãy hỏi trong kênh Discord Wandura của team bạn để nâng ngưỡng cho tổ chức. Ngưỡng mới có hiệu lực trong khoảng một phút.
  
- 1. Ngừng gửi request tới nhóm endpoint đó cho đến khi hết `Retry-After`. Retry sớm hơn chỉ nhận thêm `429`.
- 2. Tìm nguyên nhân: vòng lặp retry không có backoff, job xin vé cho cả catalog, hoặc gọi catalog mỗi lần mở app thay vì dùng cache phía server.
- 3. Nếu lưu lượng bình thường của bạn chạm ngưỡng, hãy hỏi trong kênh Discord Wandura của team bạn để được nâng ngưỡng.
+ > **Đang triển khai.** Wandura nhận cảnh báo, trong một kênh riêng, khi tổ chức của bạn chạm ngưỡng playback.
  
- ## Thói quen tốt
+ Luật retry cho mọi response: [chính sách retry](../reference/behaviour.md#retries).
  
- - Cache catalog trên server và làm mới theo lịch.
- - Chỉ xin vé playback khi người xem bắt đầu, hoặc sắp bắt đầu, một tập.
- - Đồng bộ feed creative theo kiểu incremental với `updated_since`.
- - Dùng exponential backoff có jitter cho response `5xx`. Xem [Phát mượt khi tải cao](../guides/smooth-playback.md).
+ ## Liên quan {#related}
+ 
+ - [Phát mượt khi tải cao](../guides/smooth-playback.md)
+ - [Checklist trước khi go-live](../production/go-live.md): soát ngưỡng trước khi ra mắt.

02/10/2026 · +4 −6 dòng

Xem thay đổi

⋯
  - **Theo tổ chức.** Request được đếm chung cho cả tổ chức, không theo từng key. Tạo thêm key không nâng ngưỡng của bạn.
  - **Theo nhóm endpoint.** Playback, catalog và creatives mỗi nhóm có bộ đếm riêng, nên một vòng đồng bộ creatives chạy mất kiểm soát không chặn được catalog của bạn.
- - **Cửa sổ cố định.** Bộ đếm reset khi mỗi cửa sổ thời gian bắt đầu.
+ - **Nạp lại từng giây.** Playback và catalog nạp lại hạn mức liên tục, mỗi giây một phần sáu mươi ngưỡng. Endpoint creatives dùng cửa sổ cố định, reset khi mỗi cửa sổ bắt đầu.
  - **Chỉ request đã xác thực.** Request thiếu key hoặc key không hợp lệ bị từ chối trước khi được đếm, nên không ai khác làm cạn ngưỡng của bạn được.
  
- Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`. **Đang triển khai:** request được trả bằng một vé Wandura đã cấp trước đó (xem [Quá tải nhẹ nhàng](#graceful-overload)) không bị tính, và request bị từ chối không tiêu hạn mức của bạn.
+ Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`. Request được trả bằng một vé Wandura đã cấp trước đó (xem [Quá tải nhẹ nhàng](#graceful-overload)) không bị tính, và request bị từ chối không tiêu hạn mức của bạn.
  
  ## Ngưỡng hiện tại {#limits}
⋯
  | Creatives: `GET /api/delivery/v1/creatives`, `GET /api/delivery/v1/creatives/{id}` (một bộ đếm cho cả hai) | 3.000 request | 60 giây |
  
- Mỗi cửa sổ là một phút đồng hồ (UTC), nên bộ đếm bắt đầu lại ở mỗi phút tròn. Một người xem bắt đầu một tập thường tốn khoảng ba vé playback (chính tập đó cộng các vé xin trước), nên ngưỡng playback tương đương khoảng 60 người bắt đầu xem mỗi giây.
+ Playback và catalog không có mốc phút: hạn mức được nạp lại từng giây (xem [Quá tải nhẹ nhàng](#graceful-overload)). Bộ đếm creatives dùng cửa sổ một phút đồng hồ (UTC), nên bắt đầu lại ở mỗi phút tròn. Một người xem bắt đầu một tập thường tốn khoảng ba vé playback (chính tập đó cộng các vé xin trước), nên ngưỡng playback tương đương khoảng 60 người bắt đầu xem mỗi giây.
  
  Bộ đếm chỉ xấp xỉ về phía cao: server của Wandura đếm theo lô nhỏ, nên một đợt dồn có thể lọt vài request quá ngưỡng (tối đa khoảng 2,5 % với lưu lượng bình thường) trước khi `429` bắt đầu.
⋯
  ## Quá tải nhẹ nhàng {#graceful-overload}
  
- > **Đang triển khai — chưa chạy.** Hành vi trong mục này đang được đưa lên. Trang này sẽ bỏ nhãn khi nó chạy thật. Trước đó, [ngưỡng hiện tại](#limits) vẫn hoạt động như mô tả ở trên. Code viết theo hướng dẫn [Phát mượt khi tải cao](../guides/smooth-playback.md) chạy đúng cả trước lẫn sau.
- 
  Khi gần và vượt ngưỡng, Wandura chậm lại thay vì lỗi, và ưu tiên tập người xem vừa chạm vào:
  
⋯
  | Header | Mô tả |
  |---|---|
- | `Retry-After` | Số giây cho đến khi cửa sổ hiện tại reset. **Đang triển khai:** số giây cho đến khi hạn mức nạp lại đủ, thường 1–2. |
+ | `Retry-After` | Số giây cho đến khi hạn mức nạp lại đủ, thường 1–2. Ở endpoint creatives, số giây cho đến khi cửa sổ hiện tại reset. |
  | `X-RateLimit-Limit` | Số request được phép trong mỗi cửa sổ cho nhóm endpoint này. |
  | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. |
⋯

02/10/2026 · +28 −2 dòng

Xem thay đổi

⋯
  - **Chỉ request đã xác thực.** Request thiếu key hoặc key không hợp lệ bị từ chối trước khi được đếm, nên không ai khác làm cạn ngưỡng của bạn được.
  
- Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`.
+ Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`. **Đang triển khai:** request được trả bằng một vé Wandura đã cấp trước đó (xem [Quá tải nhẹ nhàng](#graceful-overload)) không bị tính, và request bị từ chối không tiêu hạn mức của bạn.
  
  ## Ngưỡng hiện tại {#limits}
⋯
  Wandura nâng được bất kỳ ngưỡng nào ở trên riêng cho tổ chức của bạn: hỏi trong kênh Discord Wandura của team bạn. Ngưỡng mới có hiệu lực trong khoảng một phút, bạn không phải đổi gì. Wandura cũng nhận cảnh báo khi một tổ chức chạm ngưỡng playback. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
  
+ ## Quá tải nhẹ nhàng {#graceful-overload}
+ 
+ > **Đang triển khai — chưa chạy.** Hành vi trong mục này đang được đưa lên. Trang này sẽ bỏ nhãn khi nó chạy thật. Trước đó, [ngưỡng hiện tại](#limits) vẫn hoạt động như mô tả ở trên. Code viết theo hướng dẫn [Phát mượt khi tải cao](../guides/smooth-playback.md) chạy đúng cả trước lẫn sau.
+ 
+ Khi gần và vượt ngưỡng, Wandura chậm lại thay vì lỗi, và ưu tiên tập người xem vừa chạm vào:
+ 
+ | Tình huống | Điều xảy ra |
+ |---|---|
+ | Bạn dùng hết hạn mức playback | Hạn mức được **nạp lại từng giây** (ngưỡng chia 60), thay vì mỗi phút một lần. `Retry-After` cho biết bao lâu nữa có chỗ, thường **1–2 giây**. Từ lúc rảnh, bạn vẫn gửi được nguyên ngưỡng của một phút cùng lúc. |
+ | Lưu lượng playback của bạn gần chạm ngưỡng | **Prefetch bị tạm dừng trước.** Khi còn dưới khoảng 20 % hạn mức, request có `"intent": "prefetch"` nhận `429` `rate_limited` kèm `"reason": "prefetch_shed"`, trong khi request cho tập người xem vừa chạm (`"intent": "play"`, hoặc không có `intent`) vẫn được cấp vé. |
+ | Một lô có nhiều phần tử hơn chỗ còn lại | Phần tử prefetch bị từ chối trước. Phần tử nào không cấp được nhận `"status": 429` và `retry_after` riêng (kèm `"reason": "prefetch_shed"` nếu là prefetch bị tạm dừng), các phần tử còn lại vẫn nhận vé. Cả request chỉ trả `429` khi không phần tử nào cấp được. |
+ | Request `play` tới sớm hơn lúc có chỗ vài trăm mili giây | Wandura **giữ request tối đa khoảng 0,5 giây** rồi cấp vé, thay vì trả `429`. Hãy để timeout phía client ít nhất 5 giây. Request prefetch không bao giờ bị giữ. |
+ | Cùng người xem xin lại cùng một tập | Nếu bạn gửi `viewer_ref`, request lặp lại với cùng `viewer_ref`, tập, intent và giá trị thiết bị, trong lúc vé trước còn ít nhất 5 phút, nhận lại **đúng vé đó** (cùng `expires_at`, không gia hạn). Request đó không bị tính vào ngưỡng. Xem [Playback](playback.md#viewer-ref). |
+ 
+ Prefetch bị tạm dừng trả về:
+ 
+ ```json
+ {
+   "error": "Prefetch requests are paused while your playback traffic is close to its ceiling — tickets for viewers who pressed play are still issued. Retry the prefetch after Retry-After, or request it when the viewer plays.",
+   "error_code": "rate_limited",
+   "reason": "prefetch_shed"
+ }
+ ```
+ 
+ Xử lý như mọi `429`: đây không phải lỗi với người xem. Xin lại tập đó với `"intent": "play"` khi người xem chạm vào. Ngưỡng catalog cũng được nạp lại từng giây như vậy; request catalog không bao giờ bị giữ.
+ 
  ## Khi bạn chạm ngưỡng
  
⋯
  | Header | Mô tả |
  |---|---|
- | `Retry-After` | Số giây cho đến khi cửa sổ hiện tại reset. |
+ | `Retry-After` | Số giây cho đến khi cửa sổ hiện tại reset. **Đang triển khai:** số giây cho đến khi hạn mức nạp lại đủ, thường 1–2. |
  | `X-RateLimit-Limit` | Số request được phép trong mỗi cửa sổ cho nhóm endpoint này. |
  | `X-RateLimit-Window` | Độ dài cửa sổ tính bằng giây. |
⋯

02/10/2026 · +1 −1 dòng

Xem thay đổi

⋯
  - Chỉ xin vé playback khi người xem bắt đầu, hoặc sắp bắt đầu, một tập.
  - Đồng bộ feed creative theo kiểu incremental với `updated_since`.
- - Dùng exponential backoff cho response `5xx`.
+ - Dùng exponential backoff có jitter cho response `5xx`. Xem [Phát mượt khi tải cao](../guides/smooth-playback.md).

02/10/2026 · +2 −0 dòng

Xem thay đổi

⋯
  Mỗi cửa sổ là một phút đồng hồ (UTC), nên bộ đếm bắt đầu lại ở mỗi phút tròn. Một người xem bắt đầu một tập thường tốn khoảng ba vé playback (chính tập đó cộng các vé xin trước), nên ngưỡng playback tương đương khoảng 60 người bắt đầu xem mỗi giây.
  
+ Bộ đếm chỉ xấp xỉ về phía cao: server của Wandura đếm theo lô nhỏ, nên một đợt dồn có thể lọt vài request quá ngưỡng (tối đa khoảng 2,5 % với lưu lượng bình thường) trước khi `429` bắt đầu.
+ 
  Wandura nâng được bất kỳ ngưỡng nào ở trên riêng cho tổ chức của bạn: hỏi trong kênh Discord Wandura của team bạn. Ngưỡng mới có hiệu lực trong khoảng một phút, bạn không phải đổi gì. Wandura cũng nhận cảnh báo khi một tổ chức chạm ngưỡng playback. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
  
⋯

01/10/2026 · +7 −4 dòng

Xem thay đổi

⋯
  
  - **Theo tổ chức.** Request được đếm chung cho cả tổ chức, không theo từng key. Tạo thêm key không nâng ngưỡng của bạn.
- - **Theo nhóm endpoint.** Playback có bộ đếm riêng. Endpoint catalog và creatives dùng chung bộ đếm thứ hai.
+ - **Theo nhóm endpoint.** Playback, catalog và creatives mỗi nhóm có bộ đếm riêng, nên một vòng đồng bộ creatives chạy mất kiểm soát không chặn được catalog của bạn.
  - **Cửa sổ cố định.** Bộ đếm reset khi mỗi cửa sổ thời gian bắt đầu.
  - **Chỉ request đã xác thực.** Request thiếu key hoặc key không hợp lệ bị từ chối trước khi được đếm, nên không ai khác làm cạn ngưỡng của bạn được.
⋯
  | Nhóm endpoint | Ngưỡng mỗi tổ chức | Cửa sổ |
  |---|---|---|
- | Playback: `POST /api/delivery/v1/playback` | 30.000 request | 60 giây |
- | Catalog và creatives, chung một bộ đếm: `GET /api/delivery/v1/catalog`, `GET /api/delivery/v1/creatives`, `GET /api/delivery/v1/creatives/{id}` | 3.000 request | 60 giây |
+ | Playback: `POST /api/delivery/v1/playback` | 10.800 request (khoảng 180 vé mỗi giây) | 60 giây |
+ | Catalog: `GET /api/delivery/v1/catalog` | 3.000 request | 60 giây |
+ | Creatives: `GET /api/delivery/v1/creatives`, `GET /api/delivery/v1/creatives/{id}` (một bộ đếm cho cả hai) | 3.000 request | 60 giây |
  
- Mỗi cửa sổ là một phút đồng hồ (UTC), nên bộ đếm bắt đầu lại ở mỗi phút tròn. Wandura nâng được ngưỡng cho tổ chức của bạn khi bạn yêu cầu: hỏi trong kênh Discord Wandura của team bạn. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
+ Mỗi cửa sổ là một phút đồng hồ (UTC), nên bộ đếm bắt đầu lại ở mỗi phút tròn. Một người xem bắt đầu một tập thường tốn khoảng ba vé playback (chính tập đó cộng các vé xin trước), nên ngưỡng playback tương đương khoảng 60 người bắt đầu xem mỗi giây.
  
+ Wandura nâng được bất kỳ ngưỡng nào ở trên riêng cho tổ chức của bạn: hỏi trong kênh Discord Wandura của team bạn. Ngưỡng mới có hiệu lực trong khoảng một phút, bạn không phải đổi gì. Wandura cũng nhận cảnh báo khi một tổ chức chạm ngưỡng playback. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
+ 
  ## Khi bạn chạm ngưỡng
  
⋯

01/10/2026 · +10 −1 dòng

Xem thay đổi

⋯
  Mọi request xin vé đều tính vào ngưỡng playback, kể cả request có `"intent": "prefetch"`.
  
+ ## Ngưỡng hiện tại {#limits}
+ 
+ | Nhóm endpoint | Ngưỡng mỗi tổ chức | Cửa sổ |
+ |---|---|---|
+ | Playback: `POST /api/delivery/v1/playback` | 30.000 request | 60 giây |
+ | Catalog và creatives, chung một bộ đếm: `GET /api/delivery/v1/catalog`, `GET /api/delivery/v1/creatives`, `GET /api/delivery/v1/creatives/{id}` | 3.000 request | 60 giây |
+ 
+ Mỗi cửa sổ là một phút đồng hồ (UTC), nên bộ đếm bắt đầu lại ở mỗi phút tròn. Wandura nâng được ngưỡng cho tổ chức của bạn khi bạn yêu cầu: hỏi trong kênh Discord Wandura của team bạn. Trên response `429`, header `X-RateLimit-Limit` cho biết ngưỡng đang áp cho bạn.
+ 
  ## Khi bạn chạm ngưỡng
  
⋯
  1. Ngừng gửi request tới nhóm endpoint đó cho đến khi hết `Retry-After`. Retry sớm hơn chỉ nhận thêm `429`.
  2. Tìm nguyên nhân: vòng lặp retry không có backoff, job xin vé cho cả catalog, hoặc gọi catalog mỗi lần mở app thay vì dùng cache phía server.
- 3. Nếu lưu lượng bình thường của bạn chạm ngưỡng, hãy liên hệ Wandura để được nâng ngưỡng.
+ 3. Nếu lưu lượng bình thường của bạn chạm ngưỡng, hãy hỏi trong kênh Discord Wandura của team bạn để được nâng ngưỡng.
  
  ## Thói quen tốt
⋯

01/10/2026 · +1 −1 dòng

Xem thay đổi

⋯
  1. Ngừng gửi request tới nhóm endpoint đó cho đến khi hết `Retry-After`. Retry sớm hơn chỉ nhận thêm `429`.
  2. Tìm nguyên nhân: vòng lặp retry không có backoff, job xin vé cho cả catalog, hoặc gọi catalog mỗi lần mở app thay vì dùng cache phía server.
- 3. Nếu lưu lượng bình thường của bạn chạm ngưỡng, hãy liên hệ đầu mối đối tác Wandura để được nâng ngưỡng.
+ 3. Nếu lưu lượng bình thường của bạn chạm ngưỡng, hãy liên hệ Wandura để được nâng ngưỡng.
  
  ## Thói quen tốt
⋯

29/09/2026 · Tạo trang