Erros da API

Use a superfície de resposta correspondente à requisição:

• Falha HTTP: uma resposta JSON 4xx ou 5xx tem os campos estáveis code e de diagnóstico message.
• Resultado de ordem: uma resposta de ordem HTTP 200 ainda pode ser rejeitada. Verifique seus campos status e reason.
• Resposta JSON-RPC: endpoints JSON-RPC mantêm valores numéricos de error.code dentro de uma resposta HTTP 200.

Respostas de Erro HTTP

Toda resposta de erro JSON HTTP 4xx e 5xx gerada pela API inclui:

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

code é o contrato programático. Ramifique sua lógica com base nesse identificador em minúsculas e trate com segurança valores futuros desconhecidos. message é texto de diagnóstico. Exiba ou registre em log, mas não faça parsing dele.

error é um campo legado mantido. Alguns endpoints já o expõem e continuam a fazê-lo, mas ele é opaco e não faz parte do novo contrato. Campos específicos de endpoints existentes, como detalhes de prontidão e Retry-After, continuam presentes.

Respostas HEAD não têm corpo. Use o status HTTP normalmente; a Hypercall não adiciona um cabeçalho separado de código de erro.

Pré-verificação de Saque

Saques de USDC com entrega na Core verificam a ativação do destinatário e a compatibilidade da transferência antes de aceitar um novo saque. Trate withdrawal_destination_inactive e withdrawal_destination_mode_unsupported como erros de destino. withdrawal_preflight_unavailable significa que a verificação está temporariamente indisponível. withdrawal_source_unavailable exige que o serviço restaure uma conta ou rota de envio compatível.

Esses erros não criam um novo débito de saque. Uma requisição aceita anteriormente mantém seu status existente. Uma pré-verificação bem-sucedida não garante a entrega; continue monitorando o status de execução do saque. Saques somente EVM não exigem elegibilidade de conta na HyperCore.

Modo de Conta de Portfolio Margin

A portfolio margin avalia a Account a partir do seu patrimônio na HyperCore, que a HyperCore publica apenas para Accounts no modo unifiedAccount.

• POST /margin-mode com portfolio retorna 400 pm_account_not_unified quando a Account está em outro modo. Assine a diretiva hl_set_abstraction com a abstração unifiedAccount, aguarde a confirmação da HyperCore e tente novamente.
• GET /portfolio para uma Account de portfolio margin sem patrimônio atual na HyperCore retorna 409 pm_account_not_unified quando a HyperCore nunca publicou patrimônio para a Account e a reporta em outro modo. Caso contrário, retorna 503 pm_account_equity_pending até que um snapshot unificado atual chegue ao engine; quando o patrimônio retido está desatualizado e a HyperCore reporta outro modo, a mensagem informa esse modo. Tente novamente em breve após pm_account_equity_pending e reative o modo unificado se a mensagem disser que a Account saiu dele.
• account_abstraction_unavailable (503) significa que o modo de conta da HyperCore não pôde ser lido. Tente novamente em breve.

Tamanhos de Pernas de RFQ

Os tamanhos de contrato são executados em unidades de 0.000001. POST /rfq/request rejeita um tamanho de perna com mais de seis casas decimais com HTTP 400; a mensagem informa o maior tamanho executável, arredondado para baixo. A Hypercall não arredonda o tamanho por você, porque o taker assina os tamanhos exatos das pernas. Arredonde para baixo antes de assinar e reenvie.

Motivos de Pré-verificação de Cotações de RFQ

Uma cotação de maker recusada durante a pré-verificação traz um código de motivo curto. margin_rejected significa que a conta do maker falhou na verificação de margem para o pacote. pricing_unavailable significa que a plataforma não conseguiu precificar o pacote, por exemplo porque falta uma superfície de volatilidade implícita ou um preço de referência; não é uma decisão de margem, e uma nova cotação pode ser bem-sucedida assim que a precificação se recuperar.

Rejeições de Ordens

Uma ordem pode retornar HTTP 200 com um resultado de execução rejeitado:

{
  "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 é texto explicativo, não um código estável. Ele pode incluir valores ao vivo e mudar conforme a validação evolui. Para portfolio margin insuficiente, required é a margem inicial total após a ordem, enquanto os campos current_consumed_* e incremental_order_* separam o uso existente da nova ordem. Use status para identificar uma ordem rejeitada e, em seguida, exiba ou registre reason. Um contrato estável de códigos de rejeição de ordens seria um trabalho separado de protocolo e SDK.

Para ordens de perpétuos em portfolio margin, open_orders_initial_margin é a margem inicial (IM) adicional do pior estado selecionável de forma independente, não executado ou com execução total no limite, entre as ordens ativas. Uma ordem pode ser aceita enquanto a conta está abaixo da IM somente quando adicioná-la não aumenta esse envelope nem o requisito de capacidade de margem de manutenção correspondente ao pior preenchimento. Ordens abertas ainda não alteram a MM de posição publicada. Os clientes não devem inferir que a aceitação significa que a conta atual está totalmente financiada e não devem fazer parsing do reason de diagnóstico para distinguir admissão financiada de admissão que não piora o risco.

Erros JSON-RPC

GET /orderbook mantém sua resposta no estilo JSON-RPC para um instrumento inexistente, com 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
}

Ramifique sua lógica com base no error.code numérico. Códigos JSON-RPC específicos do RSM não fazem parte do catálogo HTTP público padrão.

Catálogo Público de Códigos de Erro

Este catálogo pesquisável é gerado a partir da extensão info.x-hypercall-error-codes no documento OpenAPI público. Ele contém apenas códigos HTTP voltados ao consumidor e códigos JSON-RPC sempre ativos.

Loading API error catalog…

Checklist de Tratamento

• Clientes HTTP: ramifique com base em code, preserve o status HTTP e respeite Retry-After quando presente.
• Clientes de ordens: trate status: "REJECTED" como um resultado de execução, mesmo que a requisição HTTP tenha sido bem-sucedida.
• Clientes JSON-RPC: ramifique com base no error.code numérico para o protocolo nativo do endpoint.
• Todos os clientes: mantenham um fallback seguro para códigos futuros desconhecidos e nunca façam parsing de mensagens de diagnóstico.