Giới hạn tốc độ
gioi han toc doHạn mức yêu cầu theo nhóm route của API Dòng Tiền Pro, header X-RateLimit-Limit, Remaining, Reset, mã 429 kèm Retry-After và cách thử lại đúng. han muc yeu cau theo nhom route cua api dong tien pro, header x-ratelimit-limit, remaining, reset, ma 429 kem retry-after va cach thu lai dung.API giới hạn số yêu cầu để một tích hợp lỗi vòng lặp không làm chậm người khác. Hạn mức tính theo nhóm route (x-dt-rate-class trong đặc tả OpenAPI) và theo khoá; mỗi phản hồi cho bạn biết bạn còn bao nhiêu.
Header trên mọi phản hồi
Phần tiêu đề “Header trên mọi phản hồi”| Header | Ý nghĩa |
|---|---|
X-RateLimit-Limit | Hạn mức của nhóm route trong cửa sổ hiện tại. |
X-RateLimit-Remaining | Số lần gọi còn lại trong cửa sổ. |
X-RateLimit-Reset | Thời điểm cửa sổ được đặt lại, tính bằng epoch giây. |
Retry-After | Chỉ có ở phản hồi 429: số giây nên chờ trước khi gửi lại. |
Hãy đọc X-RateLimit-Remaining để giảm tốc trước khi chạm trần, thay vì chờ tới khi nhận 429.
Hạn mức theo nhóm
Phần tiêu đề “Hạn mức theo nhóm”Bảng dưới là mức tiêu chuẩn. Hạn mức nhóm đọc có thể khác theo gói; giá trị thực tế của khoá bạn luôn nằm ở X-RateLimit-Limit.
| Nhóm | Áp dụng cho | Hạn mức |
|---|---|---|
read | Route đọc (GET) như danh sách tài khoản, giao dịch, số dư. | 600 yêu cầu mỗi phút mỗi khoá |
write | Route ghi như tạo hay cập nhật tài khoản. | 120 yêu cầu mỗi phút mỗi khoá |
collect | Route tạo yêu cầu thanh toán. | 60 yêu cầu mỗi phút mỗi khoá |
export | Route xuất dữ liệu. | 10 yêu cầu mỗi giờ |
replay | Phát lại webhook. | 30 yêu cầu mỗi phút mỗi tổ chức |
mcp | Lời gọi công cụ MCP. | 300 yêu cầu mỗi phút mỗi phiên |
Ngoài hạn mức theo nhóm còn có giới hạn đột biến ngắn hạn (100 yêu cầu trong 10 giây theo khoá); chạm giới hạn này nhận 429 với Retry-After: 10. Yêu cầu không có thông tin xác thực bị giới hạn theo địa chỉ IP, 60 yêu cầu mỗi phút.
Khi nhận 429
Phần tiêu đề “Khi nhận 429”Phản hồi 429 mang mã rate_limited, retryable: true và header Retry-After. Cách xử lý đúng:
- Chờ ít nhất
Retry-Aftergiây rồi gửi lại cùng yêu cầu. - Thêm độ trễ ngẫu nhiên nhỏ để nhiều tiến trình không cùng gửi lại một lúc.
- Giảm tốc độ gọi ở phía bạn thay vì chỉ thử lại: gom yêu cầu, dùng
limitlớn hơn (tối đa 100), hoặc dùng webhooks thay vì hỏi lại liên tục.
SDK TypeScript và Python tự thử lại 429 và tuân theo Retry-After. Nếu Retry-After lớn hơn 60 giây, SDK không ngủ chờ mà trả lỗi 429 cho mã của bạn để bạn quyết định.
Lỗi liên quan
Phần tiêu đề “Lỗi liên quan”| HTTP | Mã lỗi | Thử lại | Ý nghĩa |
|---|---|---|---|
| 429 | rate_limited | có | Gọi quá nhanh |
| 402 | quota_exceeded | không | Vượt hạn mức gói |