# Hạn mức gọi

Hạn mức tính trong cửa sổ một phút, ở ba bộ đếm tách nhau — hai bộ tính **theo từng khoá**, bộ vận đơn tính **theo shop**:

| Bộ đếm | Áp cho | Mặc định |
| --- | --- | --- |
| Chung | Mọi đường của `/api/open/v1`, trừ các đường của hai bộ bên dưới | 600 request mỗi phút mỗi khoá |
| Gửi tin | Gửi tin nhắn (`POST /conversations/:id/messages`) và trả lời riêng bình luận (`POST /comments/:id/private-reply`) | 60 request mỗi phút mỗi khoá |
| Vận đơn | Tạo vận đơn (`POST /shipments`) và huỷ vận đơn (`POST /shipments/:id/cancel`) | 60 request mỗi phút mỗi **shop**, chung cho mọi khoá của shop |

Mỗi request rơi vào đúng một bộ đếm. Request gửi tin không ăn vào 600 của bộ đếm chung, và đọc nhiều không làm cạn hạn mức gửi tin. Tạo và huỷ vận đơn gọi sang hãng vận chuyển, nên trần của chúng tính theo shop: thêm khoá không nâng được trần ấy.

Request mang khoá không hợp lệ (sai định dạng, không tồn tại) được đếm theo địa chỉ IP, và vẫn nhận 401 như thường.

## Header

Mỗi phản hồi có ba header cho biết hạn mức còn lại:

| Header | Ý nghĩa |
| --- | --- |
| `X-RateLimit-Limit` | Trần của bộ đếm áp cho request này. |
| `X-RateLimit-Remaining` | Số request còn lại trong cửa sổ hiện tại. |
| `X-RateLimit-Reset` | Số **giây** còn lại tới khi cửa sổ làm mới (không phải mốc thời gian). |

Vượt hạn mức nhận 429 với `code` là [`rate-limited`](/developers/errors#rate-limited) và header `Retry-After`: số giây phải chờ trước khi gọi lại.

## Cách xử lý

- Chủ động giãn nhịp: đọc `X-RateLimit-Remaining`, và khi gần về 0 thì chờ `X-RateLimit-Reset` giây.
- Gặp 429 thì chờ đúng `Retry-After` rồi thử lại, kèm một chút ngẫu nhiên để nhiều tiến trình không dồn vào cùng một giây.
- Đừng thử lại ngay trong vòng lặp chặt: mỗi lần thử lại cũng bị đếm.
- Khi thử lại một request tạo mới, gửi cùng [Idempotency-Key](/developers/idempotency) để không tạo trùng.
- Đồng bộ lượng lớn: dùng `limit=100` và [`updatedSince`](/developers/pagination) thay vì đọc từng bản ghi.

## Trần của bên thứ ba

Sau API của DANIX còn có trần của Facebook và Zalo khi gửi tin. Chúng áp lên **trang** chứ không lên khoá, nên không vượt được bằng cách chia nhỏ ra nhiều khoá: nhiều khoá cùng gửi qua một trang vẫn dùng chung trần của trang ấy.