Erros e Motivos de Rejeição

Catálogo completo de códigos de erro e motivos de rejeição.

Formato da Resposta de Erro

Respostas de Erro HTTP (Middleware)

Erros JSON estruturados do middleware (HTTP 4xx/5xx):

{
  "error": "<code>",
  "message": "<human message>"
}

Rejeições no Nível do Engine (HTTP 200)

Rejeições de trading retornam HTTP 200 com OrderUpdateMessage.status = "REJECTED":

{
  "timestamp": 1735000000000,
  "info": { ... },
  "status": "REJECTED",
  "reason": "<exact rejection string>",
  "filled_size": 0,
  "order_id": null,
  "wallet_address": "0x...",
  "mmp_triggered": false
}

Crítico: Não confie nos códigos de status HTTP para rejeições de trading. Sempre verifique os campos status e reason.

Códigos de Erro do Middleware

Estes são retornados como respostas de erro HTTP com corpo JSON estruturado.

Código	Status HTTP	Descrição
invalid_request	400	Não foi possível ler o corpo da requisição
invalid_json	400	Falha no parse do JSON
missing_field	400	Campo obrigatório ausente
invalid_wallet	400	A string da carteira não pôde ser interpretada
invalid_parameter	400	Parâmetro inválido (ex.: size/price devem ser strings)
signature_verification_failed	400	Falha na recuperação da assinatura EIP-712
unsupported_endpoint	400	O middleware não suporta este caminho
unauthorized	401	O signer não está autorizado para a carteira (falha na autenticação do agente)
internal_error	500	A verificação de autorização do agente falhou inesperadamente

Motivos de Rejeição do Engine

Estes aparecem em OrderUpdateMessage.reason quando status="REJECTED".

Instrumento Expirado

Motivo: "Instrument has expired"

Causa: Ordem enviada para um instrumento que já atingiu o vencimento.

Ação: Verifique o vencimento do instrumento via GET /instruments ou GET /markets.

Conta Sem Fundos

Motivo: "Account has no funds. Please deposit before trading."

Causa: O saldo em caixa da conta é <= 0.0.

Ação: Deposite USDC na carteira antes de operar.

Margem Insuficiente

Motivo: "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

Exemplo: "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

Causa: A verificação de margem pré-trade constatou que o colateral disponível (equity) é insuficiente para cobrir o requisito de margem após a ordem proposta.

Para contas de Margem Padrão, o colateral exigido depende do lado da opção, do tipo de opção, do strike, do preço do ativo subjacente e do portfólio atual. Consulte Margem Padrão para conhecer o modelo de margem vigente no lançamento.

Ação:

1. Verifique o portfólio via GET /portfolio?wallet=...
2. Revise o cálculo de margem em Margem
3. Reduza o tamanho da posição ou adicione colateral

Preço Spot Ausente

Motivo: "Failed to get portfolio: No spot price available for underlying: {underlying}"

Causa: O engine não consegue inferir o preço spot do ativo subjacente necessário para simular os preenchimentos.

Ação: Verifique a conectividade do feed de preço spot da Hyperliquid. Os preços spot vêm do feed WebSocket allMids.

Restrições de Tier

Motivo: "Tier1 users cannot go short. Filled long position: {filled}, total sell orders (including new): {total} (symbol: {symbol})"

Causa: A carteira é tier1 (apenas posições compradas) e tentou vender sem posição comprada preenchida suficiente.

Ação:

1. Verifique o tier via GET /user-tier?wallet=...
2. Garanta que todas as vendas estejam cobertas por posições compradas preenchidas
3. Entre em contato com a Hypercall se precisar de acesso de lançador (writer) para uma integração de market maker

Símbolo Inválido

Motivo: "Invalid symbol: {symbol}"

Causa: Não existe livro de ofertas para o símbolo.

Ação:

1. Verifique se o mercado existe via GET /instrument-specs e GET /markets
2. Verifique o formato do símbolo: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Erro de Parse do Símbolo

Motivo: "Failed to parse symbol: {detail}"

Causa: O símbolo não corresponde ao formato esperado.

Ação: Verifique se o formato do símbolo corresponde a UNDERLYING-EXPIRY-STRIKE-(C|P) ou ao estilo Deribit DDMMMYY.

Falhas de Cancelamento

Ordem Não Encontrada

Motivo: "Order not found for cancellation: {client_id}"

Causa: Ordem com o client_id informado não encontrada.

Ação: Verifique se o client_id está correto e se a ordem existe via GET /orders?wallet=....

Livro de Ofertas Não Encontrado

Motivo: "Orderbook not found for symbol: {symbol}"

Causa: Não existe livro de ofertas para o símbolo.

Ação: Verifique se o símbolo é válido e se o mercado existe.

Ordem Não Está no Livro de Ofertas

Motivo: "Order {id} not found in orderbook {symbol}"

Causa: O ID da ordem existe, mas a ordem não está no livro de ofertas (pode ter sido preenchida/cancelada).

Ação: Verifique o status da ordem via GET /orders?wallet=....

Ordem Já Preenchida

Motivo: "Order {id} is already filled and cannot be cancelled"

Causa: A ordem foi totalmente preenchida antes da solicitação de cancelamento.

Ação: Verifique o status da ordem via GET /orders?wallet=....

Ordem Já Cancelada

Motivo: "Order {id} was already cancelled"

Causa: A ordem já havia sido cancelada.

Ação: Verifique o status da ordem via GET /orders?wallet=....

Validação de Ordem de Perpétuo

Motivo: "Perp order missing underlying symbol"

Causa: A ordem de contrato perpétuo não inclui o campo underlying.

Ação: Garanta que a ordem de perpétuo inclua o símbolo underlying.

MMP Acionado

Motivo: "MMP triggered during fill processing"

Causa: Os limites do MMP foram violados durante o processamento do preenchimento. A ordem foi parcialmente preenchida e, em seguida, o MMP foi acionado e cancelou a quantidade restante.

Ação:

1. Verifique a configuração do MMP via GET /mmp-config?wallet=...&currency=...
2. Revise as métricas da janela de preenchimentos
3. Ajuste os limites do MMP ou reinicie o estado do MMP via POST /mmp-config/reset

Consulte MMP para a semântica completa do MMP.

Cancelamento por MMP (Outras Ordens)

Motivo: "Order canceled by MMP trigger"

Causa: A ordem foi cancelada porque outra ordem da mesma carteira+ativo subjacente acionou o MMP.

Ação: Revise a configuração do MMP e a atividade de preenchimentos.

Erros de Validação no Nível do Handler

Estes retornam HTTP 400 antes de chegar ao engine.

Validação de Preço

Erro: "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

Causa: O preço excede 5 algarismos significativos.

Ação: Arredonde o preço para ≤ 5 algarismos significativos.

Formato de Tamanho/Preço

Erro: "Size must be greater than 0" ou "Price must be greater than 0"

Causa: Tamanho ou preço é <= 0 ou não pode ser interpretado como float.

Ação: Garanta que size e price sejam números positivos válidos (como strings).

Formato de Símbolo Inválido

Erro: HTTP 400 com mensagem de erro do handler

Causa: O símbolo não é interpretado como um símbolo de opção válido.

Ação: Verifique o formato do símbolo: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Erros de Ordens em Lote

Endpoints de lote retornam erros por item em BulkOrderResult.error:

• "Signature verification failed: ..."
• "Unauthorized: signer not authorized for wallet"
• "Price validation failed: ..."
• "Size must be greater than 0"
• "Price must be greater than 0"
• "Failed to send order to engine"
• "No response from engine"

Cada resultado inclui index (posição no array da requisição) e um booleano success.

Erros de WebSocket

Mensagens de controle do WebSocket:

{
  "type": "Error",
  "message": "Authentication required for this channel"
}

Erros comuns:

• "Authentication required for this channel": Tentativa de assinar um canal privado sem ?wallet=
• "Client not found": Erro interno (conexão perdida)

Melhores Práticas de Tratamento de Erros

1. Sempre verifique o campo status: Não confie nos códigos de status HTTP para rejeições de trading
2. Faça parse da string reason: Use as strings de motivo exatas para tratamento programático
3. Trate erros em lote: Verifique BulkOrderResult.error para cada item em requisições em lote
4. Lógica de retry: Não faça retry em ordens REJECTED (corrija o problema subjacente primeiro)
5. Logging: Registre o OrderUpdateMessage completo para depurar rejeições

Tabela de Referência de Códigos de Erro

Motivo de Rejeição	Categoria	Status HTTP	Ação
Instrument has expired	Vencimento	200	Verifique o vencimento, use outro instrumento
Account has no funds...	Fundos	200	Deposite fundos (quando implementado)
Insufficient margin: ...	Margem	200	Reduza o tamanho, adicione colateral, verifique o portfólio
Failed to get portfolio: No spot price...	Dados	200	Verifique a conectividade do feed da Hyperliquid
Tier1 users cannot go short...	Tier	200	Faça upgrade para tier2 ou cubra as vendas
Invalid symbol: ...	Símbolo	200	Verifique se o mercado existe
Order not found for cancellation: ...	Cancelamento	200	Verifique se a ordem existe
Order {id} is already filled...	Cancelamento	200	Ordem já executada
Order {id} was already cancelled	Cancelamento	200	Ordem já cancelada
MMP triggered during fill processing	MMP	200	Revise a configuração do MMP, ajuste os limites
Order canceled by MMP trigger	MMP	200	Revise a configuração do MMP, ajuste os limites
signature_verification_failed	Autenticação	400	Verifique a assinatura e a codificação das strings
unauthorized	Autenticação	401	Aprove o agente ou assine com a carteira
Price validation failed: ...	Validação	400	Arredonde o preço para ≤ 5 algarismos significativos

Depurando Rejeições

1. Verifique os detalhes da ordem: Confirme que symbol, price, size e side estão corretos
2. Verifique o portfólio: GET /portfolio?wallet=... para ver posições atuais e caixa
3. Verifique o tier: GET /user-tier?wallet=... para verificar restrições de tier
4. Verifique o MMP: GET /mmp-config?wallet=...&currency=... para revisar os limites do MMP
5. Verifique o mercado: GET /markets e GET /instruments para verificar se o instrumento existe
6. Revise os logs: Os logs do servidor podem conter contexto adicional (não exposto via API)

Referências

• Lógica de rejeição: aplicada no engine de trading
• Verificações de margem: aplicadas antes da admissão da ordem
• Verificações de tier: aplicadas por tier de carteira
• Validação do handler: validação padrão de requisições