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 as atualizações perdidas
3. Reinscreva-se em 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 de Ordens

Alta Taxa de Rejeição

Sintomas: muitas ordens rejeitadas

Investigação:

1. Registre status e reason de toda resposta de ordem e de toda mensagem order_updates do WebSocket. GET /orders?wallet=... retorna as ordens abertas por padrão e não traz os motivos de rejeição
2. Revise a margem: GET /portfolio?wallet=...
3. Verifique os limites da conta: GET /risk/limits?wallet=...
4. Confirme que os instrumentos não venceram: GET /instruments?currency=...

Ações:

• Se for problema de margem: reduza o tamanho da posição ou adicione colateral
• Se for problema de tier: cubra as vendas com inventário comprado (long) ou entre em contato com a Hypercall sobre uma mudança de tier
• Se estiver vencido: use outros instrumentos

Execuções Ausentes

Sintomas: ordens executadas, mas sem notificações de execução

Investigação:

1. Verifique as execuções em GET /fills?wallet=...
2. Confirme a inscrição no canal fills do WebSocket
3. Verifique o status da conexão WebSocket

Ações:

• Reinscreva-se no canal fills
• Consulte o endpoint REST para recuperar execuções perdidas
• Reconcilie as execuções com o status das ordens

Status de Ordem Desatualizado

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

Investigação:

1. Verifique o status da conexão WebSocket
2. Confirme que o cache de ordens está atualizado
3. Compare o status da ordem no REST e no WS

Ações:

• Consulte o REST após a reconexão do WS para se atualizar
• Use o REST como fonte da 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 com um GET /mmp-config?wallet=...&currency=... assinado
2. Revise os padrões de execução e as métricas acumuladas
3. Verifique se os limites estão baixos demais

Ações:

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

MMP Não Dispara

Sintomas: as execuções excedem os limites, mas o MMP não dispara

Investigação:

1. Confirme que o MMP está habilitado com um GET /mmp-config?wallet=...&currency=... assinado
2. Verifique mmp_enabled=true nas ordens
3. Confirme que 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

Leituras assinadas do MMP enviam o vencimento e a assinatura de GetMmpConfig nos headers X-Hypercall-Expires-At-Ms e X-Hypercall-Signature.

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
• 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 um motivo que começa com "Missing spot price for underlying"

Investigação:

1. Verifique o index_price do ativo subjacente em GET /markets
2. Confirme que o símbolo do ativo subjacente está correto
3. Verifique a página de status para ver se há um incidente de oráculo

Ações:

• Aguarde a recuperação do feed de preço spot
• Use outro ativo subjacente, se disponível
• Entre em contato com 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
• Entre em contato com o suporte se o problema persistir

Rate Limiting

Sintomas: requisições rejeitadas ou limitadas

Atual: os rate limits são aplicados por carteira, com limites separados por origem para cancelamentos, autorização de agentes, escritas de MMP e simulações de risco. Veja Rate Limits para mais 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 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, até 50 ordens por requisição
2. Desconecte o WebSocket
3. Pare o sistema de cotação

Recuperação:

1. Confirme que todas as ordens foram canceladas: GET /orders?wallet=...
2. Revise o portfólio: GET /portfolio?wallet=...
3. Investigue a causa raiz
4. Retome as cotações depois que o problema for resolvido

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 as execuções: GET /fills?wallet=...
4. Reconcilie o portfólio: GET /portfolio?wallet=...
5. Retome as inscrições do WebSocket

Escalonamento

Se o problema persistir:

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