Giới hạn tần suất
Giới hạn số yêu cầu bảo vệ hệ thống cho mọi khách hàng. Vượt ngưỡng bạn nhận 429 rate_limited — hãy chờ rồi thử lại, luôn gửi Idempotency-Key cho yêu cầu ghi.
Khi vượt giới hạn, API trả 429 rate_limited kèm header Retry-After (giây). Hãy chờ đủ thời gian đó rồi mới thử lại thay vì gửi lại ngay.
Giới hạn hiện có
| Endpoint | Giới hạn | Phạm vi |
|---|---|---|
| Mọi endpoint qua cổng API | 50 yêu cầu/giây, dồn tối đa 200 | Mỗi API key |
| Mọi endpoint qua cổng API | 100 yêu cầu/giây, dồn tối đa 200 | Mỗi địa chỉ IP |
| POST /anticheat/events | 1.000 yêu cầu/phút | Mỗi tổ chức |
| GET /domains/search | 30 yêu cầu/phút | Mỗi địa chỉ IP |
Giới hạn của cổng API trả 429 rate_limited với Retry-After: 1; giới hạn theo endpoint báo thời gian chờ thật trong Retry-After.
Phản hồi khi bị giới hạn
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
"code": "rate_limited",
"message": "Bạn thao tác quá nhiều lần. Vui lòng thử lại sau 60 giây.",
"request_id": "req_4f9c2a7e"
}Idempotency
Mọi yêu cầu ghi (POST, PUT, PATCH, DELETE) phải có header Idempotency-Key dài 8–128 ký tự. Dùng khoá mới cho mỗi thao tác logic và giữ nguyên khoá khi thử lại cùng một yêu cầu:
curl -X POST https://api.lrsvn.com/v1/anticheat/events/$EVENT_ID/action \
-H "Authorization: Bearer $LRS_API_KEY" \
-H "Idempotency-Key: ignore-$EVENT_ID-1" \
-H "Content-Type: application/json" \
-d '{ "action": "ignore" }'- Gửi lại cùng khoá và cùng nội dung: nhận lại kết quả của lần đầu, thao tác không bị lặp.
- Cùng khoá nhưng nội dung khác:
409 idempotency_conflict. - Thiếu khoá hoặc độ dài sai:
422 validation_errorvớifields.idempotency_key.
Thử lại an toàn
Giữ nguyên options (kể cả Idempotency-Key) giữa các lần thử, tôn trọng Retry-After và tăng dần thời gian chờ khi gặp lỗi 5xx:
async function callWithRetry(url, options, attempts = 4) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, options);
if (res.status !== 429 && res.status < 500) return res;
const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
throw new Error("Hết số lần thử lại");
}Mã lỗi
| HTTP | Mã | Khi nào |
|---|---|---|
| 409 | idempotency_conflict | Cùng Idempotency-Key nhưng nội dung yêu cầu khác. |
| 422 | validation_error | Idempotency-Key thiếu hoặc không dài 8–128 ký tự. |
| 429 | rate_limited | Vượt giới hạn tần suất. |