本页为简体中文译文。如有歧义，请以英文原文为准。 阅读英文版 →
跳转到主要内容

API 错误

请使用与请求相匹配的响应形式：

  • HTTP 失败：4xx 或 5xx JSON 响应包含稳定的 code 字段和诊断用的 message 字段。
  • 订单结果：HTTP 200 的订单响应仍可能被拒绝。请检查其 status 和 reason。
  • JSON-RPC 响应：JSON-RPC 端点在 HTTP 200 响应中保留数值型 error.code。

HTTP 错误响应​

每个由 API 生成的 HTTP 4xx 和 5xx JSON 错误响应都包含：

{
  "error": "existing endpoint value, when present",
  "code": "invalid_field",
  "message": "price must be greater than zero"
}

code 是程序化契约。 请根据这个小写标识符进行分支处理，并安全地处理未来可能出现的未知值。message 是诊断文本。 您可以展示或记录它，但不要解析它。

error 是保留的旧版字段。 部分端点已经返回该字段并将继续返回，但它是不透明的，并非新的契约。现有的端点专用字段（例如就绪状态详情和 Retry-After）仍会保留。

HEAD 响应没有响应体。请照常使用其 HTTP 状态码；Hypercall 不会额外添加单独的错误码头部。

提现预检​

Core 交付的 USDC 提现在接受新的提现请求之前，会检查收款方的激活状态和转账兼容性。请将 withdrawal_destination_inactive 和 withdrawal_destination_mode_unsupported 作为目标地址错误处理。withdrawal_preflight_unavailable 表示验证暂时不可用。withdrawal_source_unavailable 需要服务端恢复兼容的发送账户或路由。

这些错误不会产生新的提现扣款。此前已被接受的请求保持其现有状态。预检成功并不保证到账；请继续监控提现的执行状态。仅 EVM 的提现不要求 HyperCore 账户资格。

组合保证金账户模式​

组合保证金根据 Account 的 HyperCore 权益对其估值，而 HyperCore 仅为处于 unifiedAccount 模式的 Account 发布权益数据。

  • 当 Account 处于其他模式时，使用 portfolio 调用 POST /margin-mode 会返回 400 pm_account_not_unified。请使用抽象类型 unifiedAccount 签署 hl_set_abstraction 指令，等待 HyperCore 确认后再重试。
  • 对于没有当前 HyperCore 权益的组合保证金 Account，如果 HyperCore 从未为该 Account 发布过权益且报告其处于其他模式，GET /portfolio 会返回 409 pm_account_not_unified。否则，在当前的统一模式快照到达引擎之前，它会返回 503 pm_account_equity_pending；当保留的权益已过期且 HyperCore 报告其处于其他模式时，消息中会注明该模式。遇到 pm_account_equity_pending 时请稍后重试；如果消息表明 Account 已退出统一模式，请重新启用统一模式。
  • account_abstraction_unavailable（503）表示无法读取 HyperCore 账户模式。请稍后重试。

RFQ 腿规模​

合约规模以 0.000001 为单位执行。如果某条腿的规模超过六位小数，POST /rfq/request 会以 HTTP 400 拒绝；消息中会给出向下取整后的最大可执行规模。Hypercall 不会替您对规模取整，因为 Taker 签署的是精确的腿规模。请在签名前向下取整后重新提交。

RFQ 报价预检原因​

在预检阶段被拒绝的做市商报价会附带一个简短的原因代码。margin_rejected 表示做市商账户未通过该组合的保证金检查。pricing_unavailable 表示交易场所无法对该组合估值，例如缺少隐含波动率曲面或参考价格；这不是保证金判定，定价恢复后新的报价即可成功。

订单拒绝​

订单可能返回 HTTP 200，但执行结果为拒绝：

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, equity=1200.00, shortfall=300.00, current_consumed_initial_margin=900.00, incremental_order_initial_margin=600.00, current_consumed_maintenance_margin=500.00, incremental_order_maintenance_margin=250.00"
}

reason 是说明性文本，而非稳定代码。 它可能包含实时数值，并会随着校验逻辑的演进而变化。对于组合保证金不足的情况，required 是下单后的总初始保证金，而 current_consumed_* 和 incremental_order_* 字段则将现有占用与新订单区分开来。请使用 status 识别被拒绝的订单，然后展示或记录 reason。稳定的订单拒绝代码契约将属于独立的协议和 SDK 工作。

对于组合保证金永续合约订单，open_orders_initial_margin 是所有活跃订单中，最差的可独立选择的未成交或全额限价成交状态所带来的额外初始保证金。仅当新增订单不会扩大该包络范围或对应的最差成交维持保证金容量要求时，账户在低于初始保证金的情况下才可能接受该订单。挂单仍不会改变已发布的持仓维持保证金。客户端不得据此推断订单被接受即表示当前账户资金充足，也不得解析诊断用的 reason 来区分资金充足的准入与不恶化的准入。

JSON-RPC 错误​

对于不存在的合约，GET /orderbook 保留其 JSON-RPC 风格的响应，HTTP 状态码为 200：

{
  "jsonrpc": "2.0",
  "error": {
    "code": 13020,
    "message": "not_found",
    "data": {"object": "instrument_name", "value": "BTC-20200101-1-C"}
  },
  "testnet": false,
  "usDiff": 1,
  "usIn": 1791273938274109,
  "usOut": 1791273938274109
}

请根据数值型 error.code 进行分支处理。RSM 专用的 JSON-RPC 错误码不属于默认公开的 HTTP 目录。

公开错误码目录​

此可搜索目录由公开 OpenAPI 文档中的 info.x-hypercall-error-codes 扩展生成。它仅包含面向用户的 HTTP 错误码和始终启用的 JSON-RPC 错误码。

Loading API error catalog…

处理清单​

  • HTTP 客户端：根据 code 进行分支处理，保留 HTTP 状态码，并在存在 Retry-After 时遵循该值。
  • 订单客户端：即使 HTTP 请求成功，也应将 status: "REJECTED" 视为一种执行结果。
  • JSON-RPC 客户端：针对端点的原生协议，根据数值型 error.code 进行分支处理。
  • 所有客户端：为未来未知的错误码保留安全的兜底处理，切勿解析诊断消息。
最后更新于