# Rate limit

> **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](https://docs.wandura.ai/vi/v1/developers/reference/behaviour#rate-limits).

## Cách đếm
- **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](https://docs.wandura.ai/vi/v1/developers/concepts/security#trust-boundary)).

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](https://docs.wandura.ai/vi/v1/developers/reference/behaviour#rate-limits). `GET /config` trả về các ngưỡng đang áp cho tổ chức của bạn.

## Nạp lại
| 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. |

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
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 |
|---|---|
| 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](https://docs.wandura.ai/vi/v1/developers/concepts/playback#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"
}
```

Đâ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 chạm ngưỡng
Mọi endpoint trả `429` với body phẳng, kể cả các endpoint creatives:

```json
{
  "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"
}
```

| Header (chỉ có ở `429`) | Ý nghĩa |
|---|---|
| `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á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.

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](https://docs.wandura.ai/vi/v1/developers/reference/behaviour#retries).

## Liên quan
- [Phát mượt khi tải cao](https://docs.wandura.ai/vi/v1/developers/guides/smooth-playback)
- [Checklist trước khi go-live](https://docs.wandura.ai/vi/v1/developers/production/go-live): soát ngưỡng trước khi ra mắt.