Manual de respuesta a incidentes

Procedimientos de respuesta para problemas comunes.

Problemas de conexión

Desconexión de WebSocket

Síntomas: Se pierde la conexión WebSocket, no se reciben mensajes

Acciones:

1. Implemente reconexión automática con backoff exponencial
2. Consulte los endpoints REST para recuperar las actualizaciones perdidas
3. Vuelva a suscribirse a todos los canales tras la reconexión

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

Timeout de la API

Síntomas: Las solicitudes REST agotan el tiempo de espera o devuelven errores 5xx

Acciones:

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

Prevención: Implemente limitación de solicitudes (throttling) y circuit breakers

Problemas con órdenes

Alta tasa de rechazo

Síntomas: Muchas órdenes rechazadas

Investigación:

1. Registre status y reason de cada respuesta de orden y de cada mensaje WebSocket order_updates. GET /orders?wallet=... devuelve por defecto las órdenes abiertas y no incluye los motivos de rechazo
2. Revise el margen: GET /portfolio?wallet=...
3. Compruebe los límites de la cuenta: GET /risk/limits?wallet=...
4. Verifique que los instrumentos no hayan vencido: GET /instruments?currency=...

Acciones:

• Si hay problemas de margen: reduzca el tamaño de la posición o añada colateral
• Si hay problemas de nivel (tier): cubra las ventas con inventario en posición larga, o contacte con Hypercall para solicitar un cambio de nivel
• Si el instrumento ha vencido: use otros instrumentos

Fills no recibidos

Síntomas: Órdenes ejecutadas pero sin notificaciones de fill

Investigación:

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

Acciones:

• Vuelva a suscribirse al canal fills
• Consulte el endpoint REST para obtener los fills perdidos
• Concilie los fills con el estado de las órdenes

Estado de orden desactualizado

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

Investigación:

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

Acciones:

• Consulte REST tras la reconexión de WS para ponerse al día
• Use REST como fuente de verdad para la conciliación

Problemas con MMP

MMP se activa con demasiada frecuencia

Síntomas: Muchas órdenes canceladas por MMP

Investigación:

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

Acciones:

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

MMP no se activa

Síntomas: Los fills superan los límites pero MMP no se activa

Investigación:

1. Verifique que MMP esté habilitado con un GET /mmp-config?wallet=...&currency=... firmado
2. Compruebe 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

Las lecturas firmadas de MMP envían el vencimiento y la firma de GetMmpConfig en los encabezados X-Hypercall-Expires-At-Ms y X-Hypercall-Signature.

Problemas de margen

Margen insuficiente

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

Investigación:

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

Acciones:

• Reduzca el tamaño de la posición
• Añada colateral
• Cierre posiciones para liberar margen
• Cubra la exposición para reducir la pérdida en el peor escenario

Precio spot no disponible

Síntomas: Órdenes rechazadas con un motivo que comienza por "Missing spot price for underlying"

Investigación:

1. Compruebe index_price del activo subyacente en GET /markets
2. Verifique que el símbolo del activo subyacente sea correcto
3. Consulte la página de estado por si hay un incidente del oráculo

Acciones:

• Espere a que se recupere el feed de precio spot
• Use otro activo subyacente si está disponible
• Contacte con soporte si el problema persiste

Problemas del sistema

Alta latencia

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

Investigación:

1. Compruebe la carga del sistema
2. Monitorice los tiempos de respuesta
3. Compruebe la conectividad de red

Acciones:

• Reduzca la tasa de solicitudes
• Implemente limitación de solicitudes (throttling)
• Contacte con soporte si el problema persiste

Limitación de tasa

Síntomas: Solicitudes rechazadas o limitadas

Actual: Los límites de tasa se aplican por wallet, con límites separados por origen para cancelaciones, autorización de agentes, escrituras de MMP y simulaciones de riesgo. Consulte Límites de tasa para más detalles.

Acciones:

• Revise el encabezado Retry-After y espere antes de reintentar
• Monitorice X-RateLimit-Remaining para no alcanzar los límites
• Use endpoints masivos (bulk) cuando sea posible

Procedimientos de emergencia

Kill switch

Acciones inmediatas:

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

Recuperación:

1. Verifique que todas las órdenes se hayan cancelado: GET /orders?wallet=...
2. Revise el portafolio: GET /portfolio?wallet=...
3. Investigue la causa raíz
4. Reanude la cotización una vez resuelto el problema

Conciliación de datos

Tras un incidente:

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

Escalado

Si el problema persiste:

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