Playbook d'incidents

Procédures de réponse aux problèmes courants.

Problèmes de connexion

Déconnexion WebSocket

Symptômes : connexion WebSocket perdue, aucun message reçu

Actions :

1. Mettez en place une reconnexion automatique avec backoff exponentiel
2. Interrogez les endpoints REST pour rattraper les mises à jour manquées
3. Réabonnez-vous à tous les canaux après la reconnexion

Prévention : surveillez l'état de la connexion et implémentez une logique de reconnexion robuste

Timeout de l'API

Symptômes : les requêtes REST expirent ou renvoient des erreurs 5xx

Actions :

1. Relancez avec un backoff exponentiel
2. Vérifiez l'endpoint de santé : GET /health
3. Réduisez le débit de requêtes si le système est surchargé

Prévention : implémentez une limitation du débit de requêtes et des circuit breakers

Problèmes d'ordres

Taux de rejet élevé

Symptômes : de nombreux ordres sont rejetés

Investigation :

1. Journalisez status et reason de chaque réponse d'ordre et de chaque message WebSocket order_updates. GET /orders?wallet=... renvoie par défaut les ordres ouverts et ne contient pas les motifs de rejet
2. Examinez la marge : GET /portfolio?wallet=...
3. Vérifiez les limites du compte : GET /risk/limits?wallet=...
4. Vérifiez que les instruments ne sont pas expirés : GET /instruments?currency=...

Actions :

• En cas de problème de marge : réduisez la taille de la position ou ajoutez du collatéral
• En cas de problème de palier : couvrez les ventes avec un inventaire long, ou contactez Hypercall pour un changement de palier
• En cas d'expiration : utilisez d'autres instruments

Exécutions manquantes

Symptômes : ordres exécutés mais aucune notification d'exécution

Investigation :

1. Consultez GET /fills?wallet=... pour les exécutions
2. Vérifiez l'abonnement au canal WebSocket fills
3. Vérifiez l'état de la connexion WebSocket

Actions :

• Réabonnez-vous au canal fills
• Interrogez l'endpoint REST pour récupérer les exécutions manquées
• Rapprochez les exécutions avec le statut des ordres

Statut d'ordre obsolète

Symptômes : le statut d'ordre dans REST ne correspond pas à celui du WS

Investigation :

1. Vérifiez l'état de la connexion WebSocket
2. Vérifiez que le cache d'ordres est à jour
3. Comparez le statut des ordres entre REST et WS

Actions :

• Interrogez REST après une reconnexion WS pour rattraper le retard
• Utilisez REST comme source de vérité pour le rapprochement

Problèmes de MMP

Le MMP se déclenche trop souvent

Symptômes : de nombreux ordres annulés par le MMP

Investigation :

1. Vérifiez la configuration MMP avec un GET /mmp-config?wallet=...&currency=... signé
2. Examinez les schémas d'exécution et les métriques cumulées
3. Vérifiez si les limites sont trop basses

Actions :

• Augmentez les limites MMP (qty, delta, véga)
• Augmentez interval_ms pour autoriser davantage d'exécutions dans la fenêtre
• Réduisez la fréquence de cotation

Le MMP ne se déclenche pas

Symptômes : les exécutions dépassent les limites mais le MMP ne se déclenche pas

Investigation :

1. Vérifiez que le MMP est activé avec un GET /mmp-config?wallet=...&currency=... signé
2. Vérifiez mmp_enabled=true sur les ordres
3. Vérifiez que la devise correspond au sous-jacent de l'ordre

Actions :

• Activez le MMP sur les ordres : mmp_enabled=true
• Configurez le MMP pour la bonne devise
• Ajustez les limites si nécessaire

Les lectures MMP signées transmettent l'expiration et la signature GetMmpConfig dans les en-têtes X-Hypercall-Expires-At-Ms et X-Hypercall-Signature.

Problèmes de marge

Marge insuffisante

Symptômes : ordres rejetés avec « Insufficient margin »

Investigation :

1. Consultez le portefeuille : GET /portfolio?wallet=...
2. Examinez le calcul de marge
3. Identifiez le scénario en échec

Actions :

• Réduisez la taille de la position
• Ajoutez du collatéral
• Clôturez des positions pour libérer de la marge
• Couvrez l'exposition pour réduire la perte dans le pire scénario

Prix spot manquant

Symptômes : ordres rejetés avec un motif commençant par « Missing spot price for underlying »

Investigation :

1. Vérifiez index_price pour le sous-jacent dans GET /markets
2. Vérifiez que le symbole du sous-jacent est correct
3. Consultez la page de statut pour un éventuel incident d'oracle

Actions :

• Attendez le rétablissement du flux de prix spot
• Utilisez un autre sous-jacent si disponible
• Contactez le support si le problème persiste

Problèmes système

Latence élevée

Symptômes : réponses API lentes ou retards des messages WebSocket

Investigation :

1. Vérifiez la charge du système
2. Surveillez les temps de réponse
3. Vérifiez la connectivité réseau

Actions :

• Réduisez le débit de requêtes
• Implémentez une limitation du débit de requêtes
• Contactez le support si le problème persiste

Limitation de débit

Symptômes : requêtes rejetées ou ralenties

Actuellement : les limites de débit sont appliquées par portefeuille, avec des limites distinctes par source pour les annulations, l'autorisation d'agents, les écritures MMP et les simulations de risque. Consultez Limites de débit pour plus de détails.

Actions :

• Consultez l'en-tête Retry-After et attendez avant de réessayer
• Surveillez X-RateLimit-Remaining pour éviter d'atteindre les limites
• Utilisez les endpoints groupés lorsque c'est possible

Procédures d'urgence

Kill switch

Actions immédiates :

1. Annulez tous les ordres : DELETE /bulk_order ou DELETE /bulk_order_cloid, jusqu'à 50 ordres par requête
2. Déconnectez le WebSocket
3. Arrêtez le système de cotation

Reprise :

1. Vérifiez que tous les ordres sont annulés : GET /orders?wallet=...
2. Examinez le portefeuille : GET /portfolio?wallet=...
3. Recherchez la cause racine
4. Reprenez la cotation une fois le problème résolu

Rapprochement des données

Après un incident :

1. Interrogez les endpoints REST pour obtenir l'état actuel
2. Rapprochez les ordres : GET /orders?wallet=...
3. Rapprochez les exécutions : GET /fills?wallet=...
4. Rapprochez le portefeuille : GET /portfolio?wallet=...
5. Reprenez les abonnements WebSocket

Escalade

Si le problème persiste :

1. Consultez les problèmes connus et les avis staging fournis avec votre accès
2. Consultez les Runbooks pour des procédures détaillées
3. Contactez le support en fournissant :
   • Adresse du portefeuille
   • Messages d'erreur
   • Horodatages
   • Étapes pour reproduire le problème