Giới hạn tần suất

Giới hạn tần suất theo ví cho các thao tác lệnh và yêu cầu API.

Tổng quan

Giới hạn tần suất sử dụng các cửa sổ cố định 60 giây. Giới hạn theo ví được xác định theo tier của ví và áp dụng cho:

• Đặt lệnh (POST /order, PUT /order, WebSocket PlaceOrder, và các lệnh gửi perp qua tuyến TEE)
• Hủy lệnh (DELETE /order, DELETE /order_cloid, và các lệnh hủy perp qua tuyến TEE)
• Yêu cầu API (các thao tác đọc theo phạm vi ví và các thao tác ghi có chữ ký khác)

Các giới hạn riêng, tính theo nguồn mạng và có mức trần cho toàn bộ tiến trình, áp dụng cho lệnh hủy, ủy quyền agent, thao tác ghi MMP và mô phỏng rủi ro công khai.

Bộ đếm được lưu trong bộ nhớ của từng tiến trình API. Chúng không được chia sẻ giữa các bản sao (replica), vì vậy hãy xem các con số công bố là mức tối đa mà một tiến trình đơn lẻ chấp nhận, không phải ngân sách cho toàn cụm.

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

Tier	Lệnh/phút	Hủy/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
Tier 1	30	60	300	50	20
Tier 2	120	300	1,200	500	200
Nhà tạo lập thị trường	1,200	2,400	6,000	5,000	Không giới hạn

Ví mới nhận giới hạn mặc định. Vui lòng liên hệ bộ phận hỗ trợ để nâng tier. Giới hạn yêu cầu API hiện tại của bạn nằm trong header X-RateLimit-Limit của bất kỳ thao tác đọc theo phạm vi ví nào, ví dụ GET /orders?wallet=....

Phản hồi khi vượt giới hạn

Khi vượt quá giới hạn tần suất, API 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

Các endpoint bị giới hạn theo ví trả về các header sau. Phản hồi 429 có X-RateLimit-Limit, X-RateLimit-Remaining: 0 và Retry-After, nhưng không có X-RateLimit-Reset:

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	Unix timestamp tính bằng giây khi cửa sổ được đặt lại (chỉ có ở phản hồi thành công)	1737312060
Retry-After	Số giây cần chờ trước khi thử lại (chỉ có ở 429)	45

Ví dụ 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:

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

Các loại giới hạn tần suất

Giới hạn tần suất được theo dõi riêng cho từng loại thao tác:

Đặt lệnh

Tính theo ví, so với mức Lệnh/phút của tier:

• POST /order và PUT /order
• WebSocket PlaceOrder
• POST /v1/tee-perp/orders/submit và các lệnh gửi perp khác, tính vào ví quản lý (manager) của Account

POST /bulk_order và PUT /bulk_order được giới hạn tối đa 50 mục mỗi yêu cầu.

Hủy lệnh

Tính theo ví, so với mức Hủy/phút của tier:

• DELETE /order và DELETE /order_cloid
• Lệnh hủy perp, tính vào ví API ký lệnh

Mọi route hủy lệnh, bao gồm DELETE /bulk_order và DELETE /bulk_order_cloid, cũng bị giới hạn trước bước xác minh chữ ký ở mức 6,000 lượt hủy (leg) mỗi nguồn mạng và 60,000 lượt cho toàn bộ tiến trình mỗi phút. Một lệnh hủy hàng loạt tính một lượt cho mỗi mục.

Yêu cầu API

Tính theo ví, so với mức Yêu cầu API/phút của tier:

• Các thao tác đọc theo phạm vi ví, xác định theo tham số truy vấn wallet
• Các thao tác ghi có chữ ký không được liệt kê ở trên, chẳng hạn cấu hình MMP và chế độ ký quỹ

Gửi RFQ

POST /rfq/request và các lệnh gửi RFQ qua WebSocket bị giới hạn ở mức 10 lần mỗi ví mỗi phút, không phụ thuộc vào tier.

Mô phỏng rủi ro

Các mô phỏng danh mục và lệnh công khai (POST /risk/simulate/portfolio, POST /risk/simulate/orders, và bản xem trước perp POST /v1/tee-perp/preview) có giới hạn riêng là 60 yêu cầu mỗi nguồn mạng và 600 yêu cầu cho toàn bộ tiến trình mỗi phút. Tối đa bốn mô phỏng chạy đồng thời trong một tiến trình API. Yêu cầu vượt quá hạn mức hoặc gặp lúc các worker mô phỏng đã quá tải sẽ trả về 429 Too Many Requests.

Ủy quyền agent

POST /approve-agent, DELETE /revoke-agent và DELETE /revoke-all-agents bị giới hạn trước bước xác minh chữ ký ở mức 120 yêu cầu mỗi nguồn mạng và 1,200 yêu cầu cho toàn bộ tiến trình mỗi phút.

Thao tác ghi MMP

Các thao tác ghi cấu hình MMP bị giới hạn trước bước xác minh chữ ký ở mức 120 yêu cầu mỗi nguồn mạng và 1,200 yêu cầu cho toàn bộ tiến trình mỗi phút, ngoài giới hạn yêu cầu API của ví.

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

Ngoài giới hạn tần suất, 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ả	Từ chối
Số lệnh mở tối đa	Số lệnh mở đồng thời tối đa	Lệnh mới bị từ chối khi ví đang ở mức giới hạn
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ẽ mở một vị thế mới

Đây là các trường hợp từ chối lệnh, không phải lỗi HTTP. Phản hồi lệnh là HTTP 200 với status: "REJECTED" và một reason chẳng hạn như:

max_open_orders_exceeded: current=100, limit=100
max_positions_exceeded: wallet 0x... has 50 positions, limit is 50

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

Xử lý giới hạn tần suất

1. Theo dõi header: Chủ động theo dõi X-RateLimit-Remaining
2. Tuân thủ Retry-After: Chờ đúng khoảng thời gian 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 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. Dùng endpoint hàng loạt: POST /bulk_order để gửi nhiều lệnh trong một yêu cầu
2. Gộp lệnh hủy: Dùng DELETE /bulk_order hoặc DELETE /bulk_order_cloid thay vì nhiều yêu cầu DELETE /order
3. Dùng WebSocket để nhận cập nhật: Đăng ký nhận cập nhật lệnh thay vì liên tục gọi GET /orders

Giám sát

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

• 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ã trạng thái HTTP	Mã lỗi	Mô tả
429	rate_limit_exceeded	Vượt quá giới hạn tần suất, thử lại sau khoảng thời gian chỉ định

Xem Lỗi để biết tham chiếu lỗi đầy đủ.