速率限制

针对订单操作和 API 请求的按钱包速率限制。

概述

速率限制采用固定窗口算法，按钱包执行。限制适用于：

• 下单（POST /order）
• 撤单（DELETE /order）
• API 请求（一般端点使用）

限制每 60 秒重置一次。

默认限制

等级	订单/分钟	撤单/分钟	API 请求/分钟	最大未成交订单数	最大持仓数
默认	60	120	600	100	50
等级 1	30	60	300	50	20
等级 2	120	300	1,200	500	200
做市商	600	1,200	6,000	2,000	无限制

新钱包将获得默认限制。如需升级等级，请联系支持团队。

速率限制响应

当超出速率限制时，API 会返回 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
}

响应头

所有受速率限制的端点在成功和错误响应中都包含以下响应头：

响应头	描述	示例
X-RateLimit-Limit	每个窗口允许的最大请求数	60
X-RateLimit-Remaining	当前窗口内剩余的请求数	42
X-RateLimit-Reset	窗口重置的 Unix 时间戳	1737312060
Retry-After	重试前需等待的秒数（仅在 429 时出现）	45

响应头示例

成功的请求：

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

被速率限制的请求：

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

速率限制类别

每种操作类型的速率限制分别独立跟踪：

下单

适用于：

• POST /order（期权订单）
• POST /bulk_order（批量订单，批次中的每个订单均计数）
• PUT /bulk_order（批量替换，每次替换均计数）

撤单

适用于：

• DELETE /order
• DELETE /bulk_order（批量撤单，每次撤单均计数）
• DELETE /bulk_order_cloid（按客户端订单 ID 批量撤单，每次撤单均计数）

API 请求

适用于所有需认证端点的一般 API 使用。

持仓和订单限制

除速率限制外，钱包还有最大未成交订单数和持仓数限制：

限制类型	描述	拒绝方式
最大未成交订单数	同时未成交订单的最大数量	订单在到达撮合引擎前被拒绝
最大持仓数	独立持仓的最大数量（-1 = 无限制）	若会创建新持仓则订单被拒绝

超出限制时：

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

最佳实践

处理速率限制

1. 监控响应头：主动跟踪 X-RateLimit-Remaining
2. 遵守 Retry-After：在重试前等待指定的时长
3. 实现退避策略：在连续收到 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")

优化请求使用

1. 使用批量端点：使用 POST /bulk_order 在一次请求中提交多个订单
2. 批量撤单：使用 DELETE /bulk_order 或 DELETE /bulk_order_cloid，而非多次发送 DELETE /order 请求
3. 通过 WebSocket 获取更新：订阅订单更新，而非轮询 GET /orders

监控

跟踪以下客户端指标：

• 每种操作类型的请求速率
• X-RateLimit-Remaining 的变化趋势
• 429 响应的频率
• 平均 Retry-After 时长

错误参考

HTTP 状态码	错误代码	描述
429	rate_limit_exceeded	超出速率限制，请在指定时间后重试

完整的错误参考请参见错误。