事件处理手册

常见问题的响应流程。

连接问题

WebSocket 断开

症状：WebSocket 连接丢失，收不到任何消息

处置：

1. 实现带指数退避的自动重连
2. 轮询 REST 端点以补齐遗漏的更新
3. 重连后重新订阅所有频道

预防：监控连接状态，并实现稳健的重连逻辑

API 超时

症状：REST 请求超时或返回 5xx 错误

处置：

1. 使用指数退避重试
2. 检查健康端点：GET /health
3. 如果系统过载，降低请求频率

预防：实现请求限流和熔断机制

订单问题

拒单率过高

症状：大量订单被拒绝

排查：

1. 记录每个订单响应和 WebSocket order_updates 消息中的 status 与 reason。GET /orders?wallet=... 默认只返回未成交订单，不包含拒单原因
2. 检查保证金：GET /portfolio?wallet=...
3. 检查账户限额：GET /risk/limits?wallet=...
4. 确认合约未到期：GET /instruments?currency=...

处置：

• 如果是保证金问题：减小仓位规模或追加抵押品
• 如果是等级问题：用多头持仓覆盖卖单，或联系 Hypercall 调整等级
• 如果合约已到期：改用其他合约

成交通知缺失

症状：订单已成交，但没有收到成交通知

排查：

1. 通过 GET /fills?wallet=... 查询成交记录
2. 确认已订阅 WebSocket fills 频道
3. 检查 WebSocket 连接状态

处置：

• 重新订阅 fills 频道
• 轮询 REST 端点获取遗漏的成交
• 将成交记录与订单状态进行对账

订单状态过时

症状：REST 中的订单状态与 WS 不一致

排查：

1. 检查 WebSocket 连接状态
2. 确认订单缓存为最新
3. 对比 REST 与 WS 中的订单状态

处置：

• WS 重连后轮询 REST 以补齐状态
• 对账时以 REST 为准

MMP 问题

MMP 触发过于频繁

症状：大量订单被 MMP 撤销

排查：

1. 通过签名的 GET /mmp-config?wallet=...&currency=... 检查 MMP 配置
2. 分析成交模式和累计指标
3. 检查限额是否设置过低

处置：

• 提高 MMP 限额（数量、Delta、Vega）
• 增大 interval_ms，允许窗口内有更多成交
• 降低报价频率

MMP 未触发

症状：成交已超过限额，但 MMP 未触发

排查：

1. 通过签名的 GET /mmp-config?wallet=...&currency=... 确认 MMP 已启用
2. 检查订单上是否设置了 mmp_enabled=true
3. 确认币种与订单的标的资产一致

处置：

• 在订单上启用 MMP：mmp_enabled=true
• 为正确的币种配置 MMP
• 按需调整限额

签名的 MMP 读取请求将 GetMmpConfig 的过期时间和签名分别放在 X-Hypercall-Expires-At-Ms 和 X-Hypercall-Signature 请求头中。

保证金问题

保证金不足

症状：订单因 'Insufficient margin' 被拒绝

排查：

1. 检查投资组合：GET /portfolio?wallet=...
2. 复核保证金计算
3. 确认是哪个情景未通过

处置：

• 减小仓位规模
• 追加抵押品
• 平仓以释放保证金
• 对冲敞口以降低最坏情况下的亏损

现货价格缺失

症状：订单被拒绝，原因以 'Missing spot price for underlying' 开头

排查：

1. 在 GET /markets 中检查该标的资产的 index_price
2. 确认标的资产代码正确
3. 查看状态页面是否存在预言机事件

处置：

• 等待现货价格数据源恢复
• 如有可能，改用其他标的资产
• 如果问题持续，请联系支持团队

系统问题

延迟过高

症状：API 响应缓慢或 WebSocket 消息延迟

排查：

1. 检查系统负载
2. 监控响应时间
3. 检查网络连通性

处置：

• 降低请求频率
• 实现请求限流
• 如果问题持续，请联系支持团队

速率限制

症状：请求被拒绝或被限流

现状：速率限制按钱包执行，并对撤单、代理授权、MMP 写入和风险模拟分别设有按来源的独立限额。详见速率限制。

处置：

• 检查 Retry-After 响应头，等待后再重试
• 监控 X-RateLimit-Remaining，避免触及限额
• 尽可能使用批量端点

紧急流程

紧急停止开关

立即执行：

1. 撤销所有订单：DELETE /bulk_order 或 DELETE /bulk_order_cloid，每次请求最多 50 个订单
2. 断开 WebSocket
3. 停止报价系统

恢复：

1. 确认所有订单已撤销：GET /orders?wallet=...
2. 检查投资组合：GET /portfolio?wallet=...
3. 调查根本原因
4. 问题解决后恢复报价

数据对账

事件结束后：

1. 轮询 REST 端点获取当前状态
2. 对账订单：GET /orders?wallet=...
3. 对账成交：GET /fills?wallet=...
4. 对账投资组合：GET /portfolio?wallet=...
5. 恢复 WebSocket 订阅

升级处理

如果问题持续：

1. 查阅随访问权限提供的已知问题和预发布环境通知
2. 查看运维手册了解详细流程
3. 联系支持团队，并提供：
   • 钱包地址
   • 错误信息
   • 时间戳
   • 复现步骤