Playbook de Incidentes

Procedimentos de resposta para problemas comuns.

Problemas de Conexão

Desconexão do WebSocket

Sintomas: Conexão WebSocket perdida, nenhuma mensagem recebida

Ações:

1. Implemente reconexão automática com backoff exponencial
2. Consulte os endpoints REST para recuperar atualizações perdidas
3. Reassine todos os canais após a reconexão

Prevenção: Monitore o status da conexão e implemente uma lógica de reconexão robusta

Timeout da API

Sintomas: Requisições REST expiram ou retornam erros 5xx

Ações:

1. Tente novamente com backoff exponencial
2. Verifique o endpoint de saúde: GET /health
3. Reduza a taxa de requisições se o sistema estiver sobrecarregado

Prevenção: Implemente throttling de requisições e circuit breakers

Problemas com Ordens

Alta Taxa de Rejeição

Sintomas: Muitas ordens rejeitadas

Investigação:

1. Verifique os motivos de rejeição via GET /orders?wallet=...
2. Revise a margem: GET /portfolio?wallet=...
3. Verifique o tier: GET /user-tier?wallet=...
4. Confirme que os instrumentos não estão vencidos: GET /instruments

Ações:

• Se forem problemas de margem: Reduza o tamanho da posição ou adicione colateral
• Se forem problemas de tier: Faça upgrade para tier2 ou cubra as vendas
• Se estiverem vencidos: Use instrumentos diferentes

Execuções (Fills) Ausentes

Sintomas: Ordens executadas, mas sem notificações de fill

Investigação:

1. Verifique GET /fills?wallet=... para os fills
2. Verifique a assinatura do canal fills do WebSocket
3. Verifique o status da conexão WebSocket

Ações:

• Reassine o canal fills
• Consulte o endpoint REST para fills perdidos
• Reconcilie os fills com o status das ordens

Status de Ordem Desatualizado

Sintomas: O status da ordem no REST não corresponde ao WS

Investigação:

1. Verifique o status da conexão WebSocket
2. Verifique se o cache de ordens está atualizado
3. Compare o status das ordens entre REST e WS

Ações:

• Consulte o REST após a reconexão do WS para se atualizar
• Use o REST como fonte de verdade para a reconciliação

Problemas de MMP

MMP Dispara com Muita Frequência

Sintomas: Muitas ordens canceladas pelo MMP

Investigação:

1. Verifique a configuração do MMP: GET /mmp-config?wallet=...&currency=...
2. Revise os padrões de fills e as métricas cumulativas
3. Verifique se os limites estão muito baixos

Ações:

• Aumente os limites do MMP (qty, delta, vega)
• Aumente interval_ms para permitir mais fills na janela
• Reduza a frequência de cotação

MMP Não Dispara

Sintomas: Fills excedem os limites, mas o MMP não dispara

Investigação:

1. Verifique se o MMP está habilitado: GET /mmp-config?wallet=...&currency=...
2. Verifique mmp_enabled=true nas ordens
3. Verifique se a moeda corresponde ao ativo subjacente da ordem

Ações:

• Habilite o MMP nas ordens: mmp_enabled=true
• Configure o MMP para a moeda correta
• Ajuste os limites, se necessário

Problemas de Margem

Margem Insuficiente

Sintomas: Ordens rejeitadas com "Insufficient margin"

Investigação:

1. Verifique o portfólio: GET /portfolio?wallet=...
2. Revise o cálculo de margem
3. Verifique qual cenário está falhando

Ações:

• Reduza o tamanho da posição
• Adicione colateral (quando o fluxo de depósito estiver implementado)
• Feche posições para liberar margem
• Faça hedge da exposição para reduzir a perda no pior cenário

Preço Spot Ausente

Sintomas: Ordens rejeitadas com "No spot price available"

Investigação:

1. Verifique a conectividade do feed de preço spot da Hyperliquid
2. Verifique se o símbolo do ativo subjacente está correto
3. Verifique se o feed de preço spot está operacional

Ações:

• Aguarde a recuperação do feed de preço spot
• Use outro ativo subjacente, se disponível
• Contate o suporte se o problema persistir

Problemas de Sistema

Alta Latência

Sintomas: Respostas lentas da API ou atrasos nas mensagens do WebSocket

Investigação:

1. Verifique a carga do sistema
2. Monitore os tempos de resposta
3. Verifique a conectividade de rede

Ações:

• Reduza a taxa de requisições
• Implemente throttling de requisições
• Contate o suporte se o problema persistir

Rate Limiting

Sintomas: Requisições rejeitadas ou limitadas

Atual: O rate limiting é aplicado por carteira. Veja Limites de Taxa para detalhes.

Ações:

• Verifique o header Retry-After e aguarde antes de tentar novamente
• Monitore X-RateLimit-Remaining para evitar atingir os limites
• Use endpoints em lote (bulk) quando possível

Procedimentos de Emergência

Kill Switch

Ações imediatas:

1. Cancele todas as ordens: DELETE /bulk_order ou DELETE /bulk_order_cloid
2. Desconecte o WebSocket
3. Pare o sistema de cotação

Recuperação:

1. Verifique se todas as ordens foram canceladas: GET /orders?wallet=...
2. Revise o portfólio: GET /portfolio?wallet=...
3. Investigue a causa raiz
4. Retome a cotação após a resolução do problema

Reconciliação de Dados

Após o incidente:

1. Consulte os endpoints REST para obter o estado atual
2. Reconcilie as ordens: GET /orders?wallet=...
3. Reconcilie os fills: GET /fills?wallet=...
4. Reconcilie o portfólio: GET /portfolio?wallet=...
5. Retome as assinaturas do WebSocket

Escalonamento

Se o problema persistir:

1. Revise os problemas conhecidos e os avisos de staging fornecidos com o acesso
2. Consulte os Runbooks para procedimentos detalhados
3. Contate o suporte com:
   • Endereço da carteira
   • Mensagens de erro
   • Timestamps
   • Passos para reproduzir