Giới hạn tốc độ (Rate Limits)

Giới hạn tốc độ theo từng ví cho các thao tác lệnh và yêu cầu API.

Tổng quan

Giới hạn tốc độ được áp dụng cho từng ví bằng thuật toán fixed-window (cửa sổ cố định). Giới hạn được áp dụng cho:

• Đặt lệnh (POST /order)
• Hủy lệnh (DELETE /order)
• Yêu cầu API (mức sử dụng endpoint nói chung)

Giới hạn được đặt lại sau mỗi 60 giây.

Giới hạn mặc định

Cấp độ	Lệnh/phút	Hủy lệnh/phút	Yêu cầu API/phút	Số lệnh mở tối đa	Số vị thế tối đa
Mặc định	60	120	600	100	50
Cấp 1	30	60	300	50	20
Cấp 2	120	300	1,200	500	200
Nhà tạo lập thị trường	600	1,200	6,000	2,000	Không giới hạn

Ví mới sẽ nhận mức giới hạn mặc định. Vui lòng liên hệ bộ phận hỗ trợ để nâng cấp cấp độ.

Phản hồi khi vượt giới hạn tốc độ

Khi vượt quá giới hạn tốc độ, API sẽ trả về 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for OrderPlacement: 60 per minute, retry after 45 seconds",
  "retry_after_secs": 45,
  "limit": 60
}

Header phản hồi

Tất cả các endpoint có áp dụng giới hạn tốc độ đều bao gồm các header sau trong cả phản hồi thành công lẫn phản hồi lỗi:

Header	Mô tả	Ví dụ
X-RateLimit-Limit	Số yêu cầu tối đa được phép trong mỗi cửa sổ	60
X-RateLimit-Remaining	Số yêu cầu còn lại trong cửa sổ hiện tại	42
X-RateLimit-Reset	Dấu thời gian Unix khi cửa sổ được đặt lại	1737312060
Retry-After	Số giây cần chờ trước khi thử lại (chỉ có ở mã 429)	45

Ví dụ về header phản hồi

Yêu cầu thành công:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1737312060

Yêu cầu bị giới hạn tốc độ:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1737312060

Các nhóm giới hạn tốc độ

Giới hạn tốc độ được theo dõi riêng biệt cho từng loại thao tác:

Đặt lệnh

Áp dụng cho:

• POST /order (lệnh quyền chọn)
• POST /bulk_order (lệnh hàng loạt, mỗi lệnh trong batch được tính riêng)
• PUT /bulk_order (thay thế lệnh hàng loạt, mỗi lần thay thế được tính riêng)

Hủy lệnh

Áp dụng cho:

• DELETE /order
• DELETE /bulk_order (hủy hàng loạt, mỗi lần hủy được tính riêng)
• DELETE /bulk_order_cloid (hủy hàng loạt theo client order ID, mỗi lần hủy được tính riêng)

Yêu cầu API

Áp dụng cho mức sử dụng API nói chung trên tất cả các endpoint yêu cầu xác thực.

Giới hạn vị thế và lệnh

Ngoài giới hạn tốc độ, mỗi ví còn có giới hạn số lệnh mở và số vị thế tối đa:

Loại giới hạn	Mô tả	Xử lý khi vi phạm
Số lệnh mở tối đa	Số lệnh mở đồng thời tối đa	Lệnh bị từ chối trước khi đến engine
Số vị thế tối đa	Số vị thế riêng biệt tối đa (-1 = không giới hạn)	Lệnh bị từ chối nếu sẽ tạo ra vị thế mới

Khi vượt giới hạn:

{
  "error": "limit_exceeded",
  "message": "Maximum open orders limit exceeded (100)"
}

Thực hành tốt nhất

Xử lý giới hạn tốc độ

1. Theo dõi header: Chủ động theo dõi X-RateLimit-Remaining
2. Tuân thủ Retry-After: Chờ đủ khoảng thời gian được chỉ định trước khi thử lại
3. Áp dụng backoff: Sử dụng exponential backoff khi liên tục nhận mã 429

import time

def place_order_with_retry(order, max_retries=3):
    for attempt in range(max_retries):
        response = api.place_order(order)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        return response

    raise RateLimitError("Max retries exceeded")

Tối ưu hóa việc sử dụng yêu cầu

1. Sử dụng endpoint hàng loạt: POST /bulk_order để gửi nhiều lệnh trong một yêu cầu
2. Hủy theo batch: Dùng DELETE /bulk_order hoặc DELETE /bulk_order_cloid thay vì nhiều yêu cầu DELETE /order riêng lẻ
3. Dùng WebSocket để cập nhật: Đăng ký nhận cập nhật lệnh thay vì liên tục truy vấn GET /orders

Giám sát

Theo dõi các chỉ số phía client sau:

• Tần suất yêu cầu theo từng loại thao tác
• Xu hướng của X-RateLimit-Remaining
• Tần suất phản hồi 429
• Thời lượng Retry-After trung bình

Tham chiếu lỗi

Mã HTTP	Mã lỗi	Mô tả
429	rate_limit_exceeded	Vượt quá giới hạn tốc độ, thử lại sau khoảng thời gian được chỉ định

Xem Errors để biết danh sách tham chiếu lỗi đầy đủ.