> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 速率限制

> WebSocket 交易 API 的请求限流机制，以及如何避免 RateLimited 错误

## 概要

* 速率限制按**用户**计算，覆盖该用户**所有**并发 WebSocket 连接。
* 限额为**每 60 秒 12,000 个权重单位**。
* 使用\*\*指数移动平均（EMA）\*\*模型平滑突发流量，而非简单的每秒计数器。
* 每位用户有**两个相互独立的限流桶**：
  * **通用桶**：用于订单、查询、订阅等。
  * **撤单桶**：用于撤单相关消息。
* 每类消息有内部**权重**。较重的操作（例如下单）比轻量操作（例如订阅）消耗更多额度。

> 为保护系统稳定性，限额与权重可能变化。请始终妥善处理 `RateLimited` 响应，不要假定吞吐量固定不变。

## 消息权重

当前值如下：

| 消息 | 权重 |
| - | :-: |
| `add_order` | 1.0 |
| `cancel_order` | 1.0 |
| `modify_order` | 1.0 |
| `get_order` | 2.0 |
| `get_user_orders` | 5.0 |
| `cancel_all_orders` | 2.0 |
| `get_user_trades` | 0.5 |
| `subscribe` | 0.1 |
| `unsubscribe` | 0.1 |
| `get_user_leverage` | 0.1 |
| `get_available_leverage_levels` | 0.1 |
| `set_user_leverage` | 0.1 |
| `cancel_stop_order` | 1.0 |
| `modify_stop_order` | 1.0 |
| `cancel_on_disconnect` | 0.1 |

当前限额为**每 60 秒 12,000 单位**（每秒 200 单位）。一条 `add_order`（权重 1.0）消耗 1 单位，因此可持续提交约每秒 200 笔订单。

## 限制适用范围

这些限制适用于成功认证后的 **WebSocket 入站消息**。HTTP 接口及首次 WebSocket 握手可能适用独立控制。

## 工作原理

系统维护您的**加权消息速率 EMA**。每条入站消息增加其权重；消息之间，EMA 自动衰减。

* 某个限流桶的 EMA 超过允许阈值时，该桶下一条消息会被拒绝，并返回 `RateLimited`。
* 错误包含\*\*重试等待时间（retry-after）\*\*提示，帮助客户端判断何时可以再次尝试。

由于撤单使用**独立限流桶**，即使通用桶暂时耗尽，通常仍可撤单，但仍须遵守撤单桶自身限额。

## 按用户计算，跨连接共享

多个 WebSocket 连接的流量会**汇总**到同一用户的额度中，即一个通用额度和一个撤单额度。增加连接数量**不会**提高有效限额。

## 可能收到的错误

消息被限流时，WebSocket 会收到单播错误：

```json theme={null}
{
  "type": "Err",
  "error_code": "RateLimited",
  "message": "Rate limit exceeded, retry after N seconds",
  "incoming_message": {}
}
```

使用 `retry after` 值作为重发时机的参考。

## 客户端最佳实践

1. **带随机抖动的退避**：收到 `RateLimited` 后，等待建议秒数，再加少量随机抖动（例如 50–200 毫秒）后重试，避免大量客户端同时重试。
2. **合并与批量处理**：尽量发送数量较少、目标明确的消息，而不是大量零碎消息，尤其是改单。
3. **遵守撤单额度**：独立撤单额度有助于快速降低风险，但不是无限额度，请避免撤单突发风暴。
4. **错开各连接突发流量**：多个连接共享用户额度，应错开突发请求。
5. **幂等性**：在支持的接口中使用客户端订单 ID，避免首次请求已在服务端成功时，重试产生重复订单。
6. **管理订阅**：订阅权重较低但并非免费，不要短时间内反复订阅和取消订阅。

## 常见问题

**限额按 IP 还是 API 密钥计算？**

按**用户**计算。属于同一用户的多个 API 密钥共享额度。

**读取请求是否计入限额？**

是，但权重低于写入操作。

**是否允许突发流量？**

EMA 平滑允许短时突发，但持续超过阈值会触发限流。

**能否申请提高限额？**

生产业务确实需要更高吞吐量时，请联系我们讨论专用配额。

## 变更政策

为维持平台可靠性，我们可能不定期调整限流阈值和消息权重。只要集成按上述方式处理 `RateLimited` 响应并实施退避，这类变更无需客户端更新。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.