Ошибки API

Ориентируйтесь на тот формат ответа, который соответствует запросу:

Ошибка HTTP: JSON-ответ 4xx или 5xx содержит стабильное поле code и диагностическое поле message.
Результат ордера: ответ на ордер с HTTP 200 всё равно может означать отклонение. Проверяйте поля status и reason.
Ответ JSON-RPC: эндпоинты JSON-RPC сохраняют числовые значения error.code внутри ответа HTTP 200.

Ответы с ошибками HTTP

Каждый JSON-ответ с ошибкой HTTP 4xx и 5xx, сформированный API, содержит:

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

code является программным контрактом. Стройте логику ветвления на этом идентификаторе в нижнем регистре и безопасно обрабатывайте неизвестные значения, которые могут появиться в будущем. message содержит диагностический текст. Показывайте или логируйте его, но не разбирайте.

error оставлено как унаследованное поле. Некоторые эндпоинты уже возвращают его и продолжат это делать, но поле непрозрачно и не входит в новый контракт. Существующие поля, специфичные для эндпоинтов, например сведения о готовности и Retry-After, сохраняются.

Ответы на HEAD не содержат тела. Используйте их HTTP-статус как обычно; Hypercall не добавляет отдельный заголовок с кодом ошибки.

Предварительная проверка вывода средств

При выводе USDC с доставкой на Core система до приёма нового вывода проверяет активацию получателя и совместимость перевода. Обрабатывайте withdrawal_destination_inactive и withdrawal_destination_mode_unsupported как ошибки адреса назначения. withdrawal_preflight_unavailable означает, что проверка временно недоступна. withdrawal_source_unavailable требует, чтобы сервис восстановил совместимый аккаунт или маршрут отправки.

Эти ошибки не создают нового списания по выводу. Ранее принятый запрос сохраняет свой текущий статус. Успешная предварительная проверка не гарантирует доставку; продолжайте отслеживать статус исполнения вывода. Выводы только в EVM не требуют соответствия аккаунта на HyperCore.

Режим аккаунта для портфельной маржи

Портфельная маржа оценивает аккаунт по его капиталу (equity) на HyperCore, который HyperCore публикует только для аккаунтов в режиме unifiedAccount.

POST /margin-mode со значением portfolio возвращает 400 pm_account_not_unified, если аккаунт находится в другом режиме. Подпишите директиву hl_set_abstraction с абстракцией unifiedAccount, дождитесь подтверждения от HyperCore и повторите запрос.
GET /portfolio для аккаунта с портфельной маржой без актуального капитала на HyperCore возвращает 409 pm_account_not_unified, если HyperCore ни разу не публиковал капитал для аккаунта и сообщает, что аккаунт в другом режиме. В остальных случаях возвращается 503 pm_account_equity_pending, пока актуальный снимок в едином режиме не дойдёт до движка; если сохранённое значение капитала устарело, а HyperCore сообщает о другом режиме, в сообщении указывается этот режим. Повторите запрос при pm_account_equity_pending через короткое время и снова включите единый режим, если в сообщении сказано, что аккаунт из него вышел.
account_abstraction_unavailable (503) означает, что режим аккаунта на HyperCore не удалось прочитать. Повторите запрос через короткое время.

Размеры ног RFQ

Размеры контрактов исполняются с шагом 0.000001. POST /rfq/request отклоняет размер ноги с более чем шестью знаками после запятой, возвращая HTTP 400; в сообщении указывается наибольший исполнимый размер, округлённый вниз. Hypercall не округляет размер за вас, поскольку тейкер подписывает точные размеры ног. Округлите вниз до подписи и отправьте запрос повторно.

Причины отказа при предварительной проверке котировок 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 представляет собой дополнительную начальную маржу (IM) от наихудшего независимо выбираемого состояния (неисполненного или полностью исполненного по лимиту) среди активных ордеров. Ордер может быть принят, когда аккаунт ниже уровня IM, только если его добавление не увеличивает эту огибающую или соответствующее требование к поддерживающей марже при наихудшем исполнении. Открытые ордера по-прежнему не меняют опубликованную поддерживающую маржу (MM) позиции. Клиенты не должны делать вывод, что принятие ордера означает полное обеспечение текущего аккаунта, и не должны разбирать диагностическое поле 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. Коды JSON-RPC, специфичные для RSM, не входят в публичный каталог HTTP по умолчанию.

Публичный каталог кодов ошибок

Этот каталог с поиском генерируется из расширения info.x-hypercall-error-codes в публичном документе OpenAPI. Он содержит только клиентские HTTP-коды и постоянно действующие коды JSON-RPC.

Loading API error catalog…

Чек-лист обработки

HTTP-клиенты: стройте ветвление на code, сохраняйте HTTP-статус и соблюдайте Retry-After, если он присутствует.
Клиенты ордеров: считайте status: "REJECTED" результатом исполнения, даже если HTTP-запрос завершился успешно.
Клиенты JSON-RPC: стройте ветвление на числовом error.code в рамках собственного протокола эндпоинта.
Все клиенты: предусмотрите безопасную обработку неизвестных будущих кодов и никогда не разбирайте диагностические сообщения.

Ответы с ошибками HTTP​

Предварительная проверка вывода средств​

Режим аккаунта для портфельной маржи​

Размеры ног RFQ​

Причины отказа при предварительной проверке котировок RFQ​

Отклонения ордеров​

Ошибки JSON-RPC​

Публичный каталог кодов ошибок​

Чек-лист обработки​