Erreurs et motifs de rejet

Catalogue complet des codes d'erreur et des motifs de rejet.

Format des réponses d'erreur

Réponses d'erreur HTTP (Middleware)

Erreurs JSON structurées provenant du middleware (HTTP 4xx/5xx) :

{
  "error": "<code>",
  "message": "<human message>"
}

Rejets au niveau du moteur (HTTP 200)

Les rejets de trading renvoient HTTP 200 avec OrderUpdateMessage.status = "REJECTED" :

{
  "timestamp": 1735000000000,
  "info": { ... },
  "status": "REJECTED",
  "reason": "<exact rejection string>",
  "filled_size": 0,
  "order_id": null,
  "wallet_address": "0x...",
  "mmp_triggered": false
}

Critique : Ne vous fiez pas aux codes de statut HTTP pour les rejets de trading. Vérifiez toujours les champs status et reason.

Codes d'erreur du middleware

Ceux-ci sont renvoyés sous forme de réponses d'erreur HTTP avec un corps JSON structuré.

Code	Statut HTTP	Description
invalid_request	400	Impossible de lire le corps de la requête
invalid_json	400	Échec de l'analyse JSON
missing_field	400	Champ requis manquant
invalid_wallet	400	La chaîne du portefeuille n'a pas pu être analysée
invalid_parameter	400	Paramètre invalide (par ex., size/price doit être une chaîne)
signature_verification_failed	400	Échec de la récupération de la signature EIP-712
unsupported_endpoint	400	Le middleware ne prend pas en charge ce chemin
unauthorized	401	Le signataire n'est pas autorisé pour ce portefeuille (échec de l'authentification de l'agent)
internal_error	500	La vérification d'autorisation de l'agent a échoué de manière inattendue

Motifs de rejet du moteur

Ceux-ci apparaissent dans OrderUpdateMessage.reason lorsque status="REJECTED".

Instrument expiré

Motif : "Instrument has expired"

Cause : Ordre placé sur un instrument dont l'échéance est déjà passée.

Action : Vérifiez l'échéance de l'instrument via GET /instruments ou GET /markets.

Compte non approvisionné

Motif : "Account has no funds. Please deposit before trading."

Cause : Le solde en espèces du compte est <= 0.0.

Action : Approvisionnez le portefeuille en USDC avant de trader.

Marge insuffisante

Motif : "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

Exemple : "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

Cause : La vérification de marge pré-négociation a constaté que le collatéral disponible (capitaux propres) est insuffisant pour couvrir l'exigence de marge après l'ordre proposé.

Pour les comptes en marge standard, le collatéral requis dépend du sens de l'option, du type d'option, du prix d'exercice, du prix du sous-jacent et du portefeuille actuel. Consultez Standard Margin pour le modèle de marge en vigueur au lancement.

Action :

1. Vérifiez le portefeuille via GET /portfolio?wallet=...
2. Examinez le calcul de la marge dans Margin
3. Réduisez la taille de la position ou ajoutez du collatéral

Prix spot manquant

Motif : "Failed to get portfolio: No spot price available for underlying: {underlying}"

Cause : Le moteur ne peut pas déduire le prix spot du sous-jacent nécessaire pour simuler les exécutions.

Action : Vérifiez la connectivité du flux de prix spot Hyperliquid. Les prix spot proviennent du flux WebSocket allMids.

Restrictions de tier

Motif : "Tier1 users cannot go short. Filled long position: {filled}, total sell orders (including new): {total} (symbol: {symbol})"

Cause : Le portefeuille est tier1 (positions longues uniquement) et a tenté de vendre sans une position longue exécutée suffisante.

Action :

1. Vérifiez le tier via GET /user-tier?wallet=...
2. Assurez-vous que toutes les ventes sont couvertes par des positions longues exécutées
3. Contactez Hypercall si vous avez besoin d'un accès vendeur pour une intégration de market maker

Symbole invalide

Motif : "Invalid symbol: {symbol}"

Cause : Aucun carnet d'ordres n'existe pour ce symbole.

Action :

1. Vérifiez que le marché existe via GET /instrument-specs et GET /markets
2. Vérifiez le format du symbole : UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Erreur d'analyse du symbole

Motif : "Failed to parse symbol: {detail}"

Cause : Le symbole ne correspond pas au format attendu.

Action : Vérifiez que le format du symbole correspond à UNDERLYING-EXPIRY-STRIKE-(C|P) ou au style Deribit DDMMMYY.

Échecs d'annulation

Ordre introuvable

Motif : "Order not found for cancellation: {client_id}"

Cause : L'ordre avec le client_id donné est introuvable.

Action : Vérifiez que le client_id est correct et que l'ordre existe via GET /orders?wallet=....

Carnet d'ordres introuvable

Motif : "Orderbook not found for symbol: {symbol}"

Cause : Le carnet d'ordres n'existe pas pour ce symbole.

Action : Vérifiez que le symbole est valide et que le marché existe.

Ordre absent du carnet d'ordres

Motif : "Order {id} not found in orderbook {symbol}"

Cause : L'identifiant de l'ordre existe mais l'ordre n'est pas dans le carnet d'ordres (il a peut-être été exécuté/annulé).

Action : Vérifiez le statut de l'ordre via GET /orders?wallet=....

Ordre déjà exécuté

Motif : "Order {id} is already filled and cannot be cancelled"

Cause : L'ordre a été entièrement exécuté avant la demande d'annulation.

Action : Vérifiez le statut de l'ordre via GET /orders?wallet=....

Ordre déjà annulé

Motif : "Order {id} was already cancelled"

Cause : L'ordre était déjà annulé.

Action : Vérifiez le statut de l'ordre via GET /orders?wallet=....

Validation des ordres perpétuels

Motif : "Perp order missing underlying symbol"

Cause : L'ordre sur contrat perpétuel n'inclut pas le champ underlying.

Action : Assurez-vous que l'ordre perpétuel inclut le symbole underlying.

MMP déclenché

Motif : "MMP triggered during fill processing"

Cause : Les limites MMP ont été dépassées pendant le traitement des exécutions. L'ordre a été partiellement exécuté, puis le MMP s'est déclenché et a annulé la quantité restante.

Action :

1. Vérifiez la configuration MMP via GET /mmp-config?wallet=...&currency=...
2. Examinez les métriques de la fenêtre d'exécution
3. Ajustez les limites MMP ou réinitialisez l'état MMP via POST /mmp-config/reset

Consultez MMP pour la sémantique complète du MMP.

Annulation MMP (autres ordres)

Motif : "Order canceled by MMP trigger"

Cause : L'ordre a été annulé parce qu'un autre ordre pour la même paire portefeuille+sous-jacent a déclenché le MMP.

Action : Examinez la configuration MMP et l'activité d'exécution.

Erreurs de validation au niveau du handler

Celles-ci renvoient HTTP 400 avant d'atteindre le moteur.

Validation du prix

Erreur : "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

Cause : Le prix dépasse 5 chiffres significatifs.

Action : Arrondissez le prix à ≤ 5 chiffres significatifs.

Format de taille/prix

Erreur : "Size must be greater than 0" ou "Price must be greater than 0"

Cause : La taille ou le prix est <= 0 ou ne peut pas être analysé comme nombre flottant.

Action : Assurez-vous que size et price sont des nombres positifs valides (sous forme de chaînes).

Format de symbole invalide

Erreur : HTTP 400 avec message d'erreur du handler

Cause : Le symbole ne peut pas être analysé comme un symbole d'option valide.

Action : Vérifiez le format du symbole : UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Erreurs d'ordres groupés

Les endpoints d'ordres groupés renvoient des erreurs par élément dans BulkOrderResult.error :

• "Signature verification failed: ..."
• "Unauthorized: signer not authorized for wallet"
• "Price validation failed: ..."
• "Size must be greater than 0"
• "Price must be greater than 0"
• "Failed to send order to engine"
• "No response from engine"

Chaque résultat inclut index (position dans le tableau de la requête) et un booléen success.

Erreurs WebSocket

Messages de contrôle WebSocket :

{
  "type": "Error",
  "message": "Authentication required for this channel"
}

Erreurs courantes :

• "Authentication required for this channel" : Tentative d'abonnement à un canal privé sans ?wallet=
• "Client not found" : Erreur interne (connexion perdue)

Bonnes pratiques de gestion des erreurs

1. Vérifiez toujours le champ status : Ne vous fiez pas aux codes de statut HTTP pour les rejets de trading
2. Analysez la chaîne reason : Utilisez les chaînes de motif exactes pour un traitement programmatique
3. Gérez les erreurs groupées : Vérifiez BulkOrderResult.error pour chaque élément des requêtes groupées
4. Logique de nouvelle tentative : Ne réessayez pas les ordres REJECTED (corrigez d'abord le problème sous-jacent)
5. Journalisation : Enregistrez l'intégralité du OrderUpdateMessage pour déboguer les rejets

Tableau de référence des codes d'erreur

Motif de rejet	Catégorie	Statut HTTP	Action
Instrument has expired	Échéance	200	Vérifiez l'échéance, utilisez un autre instrument
Account has no funds...	Financement	200	Déposez des fonds (une fois implémenté)
Insufficient margin: ...	Marge	200	Réduisez la taille, ajoutez du collatéral, vérifiez le portefeuille
Failed to get portfolio: No spot price...	Données	200	Vérifiez la connectivité du flux Hyperliquid
Tier1 users cannot go short...	Tier	200	Passez au tier2 ou couvrez les ventes
Invalid symbol: ...	Symbole	200	Vérifiez que le marché existe
Order not found for cancellation: ...	Annulation	200	Vérifiez que l'ordre existe
Order {id} is already filled...	Annulation	200	Ordre déjà exécuté
Order {id} was already cancelled	Annulation	200	Ordre déjà annulé
MMP triggered during fill processing	MMP	200	Examinez la config MMP, ajustez les limites
Order canceled by MMP trigger	MMP	200	Examinez la config MMP, ajustez les limites
signature_verification_failed	Auth	400	Vérifiez la signature, l'encodage des chaînes
unauthorized	Auth	401	Approuvez l'agent ou signez avec le portefeuille
Price validation failed: ...	Validation	400	Arrondissez le prix à ≤ 5 chiffres significatifs

Débogage des rejets

1. Vérifiez les détails de l'ordre : Vérifiez que symbol, price, size, side sont corrects
2. Vérifiez le portefeuille : GET /portfolio?wallet=... pour voir les positions actuelles et les liquidités
3. Vérifiez le tier : GET /user-tier?wallet=... pour vérifier les restrictions de tier
4. Vérifiez le MMP : GET /mmp-config?wallet=...&currency=... pour examiner les limites MMP
5. Vérifiez le marché : GET /markets et GET /instruments pour vérifier que l'instrument existe
6. Examinez les journaux : Les journaux du serveur peuvent contenir un contexte supplémentaire (non exposé via l'API)

Références

• Logique de rejet : appliquée dans le moteur de trading
• Vérifications de marge : appliquées avant l'admission de l'ordre
• Vérifications de tier : appliquées par tier de portefeuille
• Validation du handler : validation standard des requêtes