# 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.
- **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.

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
| 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 |

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

Mọi endpoint, kể cả endpoint creatives, đều trả `429 Too Many Requests` với body lỗi phẳng:

```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_code": "rate_limited"
}
```

Response kèm các header sau:

| Header | Mô tả |
|---|---|
| `Retry-After` | 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. |

Các header giới hạn chỉ xuất hiện trên response `429`.

## Cách khôi phục

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.

## Thói quen tốt

- 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 cho response `5xx`.