Playbook de Incidentes

Procedimientos de respuesta para problemas comunes.

Problemas de Conexión

Desconexión de WebSocket

Síntomas: Conexión WebSocket perdida, no se reciben mensajes

Acciones:

1. Implemente reconexión automática con backoff exponencial
2. Consulte los endpoints REST para ponerse al día con las actualizaciones perdidas
3. Vuelva a suscribirse a todos los canales después de la reconexión

Prevención: Monitoree el estado de la conexión e implemente una lógica de reconexión robusta

Timeout de API

Síntomas: Las solicitudes REST expiran o devuelven errores 5xx

Acciones:

1. Reintente con backoff exponencial
2. Verifique el endpoint de salud: GET /health
3. Reduzca la tasa de solicitudes si el sistema está sobrecargado

Prevención: Implemente limitación de solicitudes y circuit breakers

Problemas con Órdenes

Alta Tasa de Rechazo

Síntomas: Muchas órdenes rechazadas

Investigación:

1. Verifique los motivos de rechazo mediante GET /orders?wallet=...
2. Revise el margen: GET /portfolio?wallet=...
3. Verifique el tier: GET /user-tier?wallet=...
4. Verifique que los instrumentos no hayan vencido: GET /instruments

Acciones:

• Si hay problemas de margen: Reduzca el tamaño de la posición o agregue colateral
• Si hay problemas de tier: Actualice a tier2 o cubra las ventas
• Si han vencido: Utilice instrumentos diferentes

Ejecuciones Faltantes

Síntomas: Órdenes ejecutadas pero sin notificaciones de ejecución

Investigación:

1. Consulte GET /fills?wallet=... para ver las ejecuciones
2. Verifique la suscripción al canal fills del WebSocket
3. Verifique el estado de la conexión WebSocket

Acciones:

• Vuelva a suscribirse al canal fills
• Consulte el endpoint REST para las ejecuciones perdidas
• Concilie las ejecuciones con el estado de las órdenes

Estado de Órdenes Desactualizado

Síntomas: El estado de la orden en REST no coincide con el de WS

Investigación:

1. Verifique el estado de la conexión WebSocket
2. Verifique que la caché de órdenes esté actualizada
3. Compare el estado de las órdenes entre REST y WS

Acciones:

• Consulte REST después de la reconexión de WS para ponerse al día
• Utilice REST como fuente de verdad para la conciliación

Problemas de MMP

MMP Se Activa Con Demasiada Frecuencia

Síntomas: Muchas órdenes canceladas por MMP

Investigación:

1. Verifique la configuración de MMP: GET /mmp-config?wallet=...&currency=...
2. Revise los patrones de ejecución y las métricas acumuladas
3. Verifique si los límites son demasiado bajos

Acciones:

• Aumente los límites de MMP (qty, delta, vega)
• Aumente interval_ms para permitir más ejecuciones en la ventana
• Reduzca la frecuencia de cotización

MMP No Se Activa

Síntomas: Las ejecuciones exceden los límites pero MMP no se activa

Investigación:

1. Verifique que MMP esté habilitado: GET /mmp-config?wallet=...&currency=...
2. Verifique mmp_enabled=true en las órdenes
3. Verifique que la moneda coincida con el activo subyacente de la orden

Acciones:

• Habilite MMP en las órdenes: mmp_enabled=true
• Configure MMP para la moneda correcta
• Ajuste los límites si es necesario

Problemas de Margen

Margen Insuficiente

Síntomas: Órdenes rechazadas con "Insufficient margin"

Investigación:

1. Verifique el portafolio: GET /portfolio?wallet=...
2. Revise el cálculo del margen
3. Verifique qué escenario está fallando

Acciones:

• Reduzca el tamaño de la posición
• Agregue colateral (cuando el flujo de depósito esté implementado)
• Cierre posiciones para liberar margen
• Realice cobertura de la exposición para reducir la pérdida en el peor escenario

Precio Spot Faltante

Síntomas: Órdenes rechazadas con "No spot price available"

Investigación:

1. Verifique la conectividad del feed de precios spot de Hyperliquid
2. Verifique que el símbolo del activo subyacente sea correcto
3. Verifique si el feed de precios spot está operativo

Acciones:

• Espere a que el feed de precios spot se recupere
• Utilice un activo subyacente diferente si está disponible
• Contacte a soporte si el problema persiste

Problemas del Sistema

Alta Latencia

Síntomas: Respuestas lentas de la API o retrasos en los mensajes de WebSocket

Investigación:

1. Verifique la carga del sistema
2. Monitoree los tiempos de respuesta
3. Verifique la conectividad de red

Acciones:

• Reduzca la tasa de solicitudes
• Implemente limitación de solicitudes
• Contacte a soporte si el problema persiste

Límites de Tasa

Síntomas: Solicitudes rechazadas o limitadas

Actual: Los límites de tasa se aplican por wallet. Consulte Límites de Tasa para más detalles.

Acciones:

• Verifique el encabezado Retry-After y espere antes de reintentar
• Monitoree X-RateLimit-Remaining para evitar alcanzar los límites
• Utilice endpoints masivos cuando sea posible

Procedimientos de Emergencia

Kill Switch

Acciones inmediatas:

1. Cancele todas las órdenes: DELETE /bulk_order o DELETE /bulk_order_cloid
2. Desconecte el WebSocket
3. Detenga el sistema de cotización

Recuperación:

1. Verifique que todas las órdenes estén canceladas: GET /orders?wallet=...
2. Revise el portafolio: GET /portfolio?wallet=...
3. Investigue la causa raíz
4. Reanude la cotización después de resolver el problema

Conciliación de Datos

Después de un incidente:

1. Consulte los endpoints REST para obtener el estado actual
2. Concilie las órdenes: GET /orders?wallet=...
3. Concilie las ejecuciones: GET /fills?wallet=...
4. Concilie el portafolio: GET /portfolio?wallet=...
5. Reanude las suscripciones de WebSocket

Escalamiento

Si el problema persiste:

1. Revise los problemas conocidos y los avisos de staging proporcionados con el acceso
2. Consulte los Runbooks para procedimientos detallados
3. Contacte a soporte con:
   • Dirección de wallet
   • Mensajes de error
   • Marcas de tiempo
   • Pasos para reproducir el problema