Erreurs de l'API

Utilisez la surface de réponse qui correspond à la requête :

• Échec HTTP : une réponse JSON 4xx ou 5xx contient un champ code stable et un champ message de diagnostic.
• Résultat d'ordre : une réponse d'ordre HTTP 200 peut tout de même être rejetée. Vérifiez ses champs status et reason.
• Réponse JSON-RPC : les endpoints JSON-RPC conservent des valeurs numériques error.code à l'intérieur d'une réponse HTTP 200.

Réponses d'erreur HTTP

Chaque réponse d'erreur JSON HTTP 4xx et 5xx générée par l'API inclut :

{
  "error": "existing endpoint value, when present",
  "code": "invalid_field",
  "message": "price must be greater than zero"
}

code constitue le contrat programmatique. Basez vos branchements sur cet identifiant en minuscules et traitez de manière sûre les futures valeurs inconnues. message est un texte de diagnostic. Affichez-le ou journalisez-le, mais ne l'analysez pas.

error est un champ historique conservé. Certains endpoints l'exposent déjà et continuent de le faire, mais il est opaque et ne fait pas partie du nouveau contrat. Les champs propres à certains endpoints, tels que les détails de disponibilité et Retry-After, restent présents.

Les réponses HEAD n'ont pas de corps. Utilisez leur statut HTTP normalement ; Hypercall n'ajoute pas d'en-tête distinct pour le code d'erreur.

Vérification préalable des retraits

Les retraits USDC livrés sur Core vérifient l'activation du destinataire et la compatibilité du transfert avant d'accepter un nouveau retrait. Traitez withdrawal_destination_inactive et withdrawal_destination_mode_unsupported comme des erreurs de destination. withdrawal_preflight_unavailable signifie que la vérification est temporairement indisponible. withdrawal_source_unavailable exige que le service rétablisse un compte émetteur ou une route compatible.

Ces erreurs ne créent pas de nouveau débit de retrait. Une demande déjà acceptée conserve son statut existant. Une vérification préalable réussie ne garantit pas la livraison ; continuez à surveiller le statut d'exécution du retrait. Les retraits uniquement EVM ne nécessitent pas d'éligibilité de compte HyperCore.

Mode de compte pour la marge de portefeuille

La marge de portefeuille valorise l'Account à partir de son equity HyperCore, que HyperCore ne publie que pour les Accounts en mode unifiedAccount.

• POST /margin-mode avec portfolio renvoie 400 pm_account_not_unified lorsque l'Account est dans un autre mode. Signez la directive hl_set_abstraction avec l'abstraction unifiedAccount, attendez que HyperCore la confirme, puis réessayez.
• GET /portfolio pour un Account en marge de portefeuille sans equity HyperCore actuelle renvoie 409 pm_account_not_unified lorsque HyperCore n'a jamais publié d'equity pour l'Account et le signale dans un autre mode. Sinon, il renvoie 503 pm_account_equity_pending jusqu'à ce qu'un instantané unifié actuel parvienne au moteur ; lorsque l'equity conservée est périmée et que HyperCore signale un autre mode, le message indique ce mode. Réessayez peu après en cas de pm_account_equity_pending, et réactivez le mode unifié si le message indique que l'Account l'a quitté.
• account_abstraction_unavailable (503) signifie que le mode de compte HyperCore n'a pas pu être lu. Réessayez peu après.

Tailles des jambes RFQ

Les tailles de contrat s'exécutent par unités de 0.000001. POST /rfq/request rejette avec un HTTP 400 toute taille de jambe comportant plus de six décimales ; le message indique la plus grande taille exécutable, arrondie à l'inférieur. Hypercall n'arrondit pas la taille à votre place, car le preneur signe les tailles exactes des jambes. Arrondissez à l'inférieur avant de signer, puis soumettez à nouveau.

Motifs de vérification préalable des cotations RFQ

Une cotation de market maker refusée lors de la vérification préalable porte un code de motif court. margin_rejected signifie que le compte du market maker n'a pas passé le contrôle de marge pour le package. pricing_unavailable signifie que la plateforme n'a pas pu valoriser le package, par exemple parce qu'une surface de volatilité implicite ou un prix de référence est manquant ; il ne s'agit pas d'une décision de marge, et une nouvelle cotation peut aboutir une fois la valorisation rétablie.

Rejets d'ordres

Un ordre peut renvoyer HTTP 200 avec un résultat d'exécution rejeté :

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, equity=1200.00, shortfall=300.00, current_consumed_initial_margin=900.00, incremental_order_initial_margin=600.00, current_consumed_maintenance_margin=500.00, incremental_order_maintenance_margin=250.00"
}

reason est un texte explicatif, pas un code stable. Il peut inclure des valeurs en direct et évoluer avec les règles de validation. En cas de marge de portefeuille insuffisante, required correspond à la marge initiale totale après l'ordre, tandis que les champs current_consumed_* et incremental_order_* distinguent l'utilisation existante du nouvel ordre. Utilisez status pour identifier un ordre rejeté, puis affichez ou journalisez reason. Un contrat stable de codes de rejet d'ordre relèverait d'un travail distinct sur le protocole et le SDK.

Pour les ordres sur contrats perpétuels en marge de portefeuille, open_orders_initial_margin est l'IM supplémentaire issue du pire état sélectionnable indépendamment, non exécuté ou entièrement exécuté à la limite, parmi les ordres actifs. Un ordre peut être accepté alors que le compte est sous l'IM uniquement si son ajout n'augmente ni cette enveloppe ni l'exigence de capacité de maintenance correspondante au pire cas d'exécution. Les ordres ouverts ne modifient toujours pas la MM de position publiée. Les clients ne doivent pas déduire de l'acceptation que le compte actuel est entièrement financé, et ne doivent pas analyser le reason de diagnostic pour distinguer une admission financée d'une admission sans aggravation.

Erreurs JSON-RPC

GET /orderbook conserve sa réponse de style JSON-RPC pour un instrument manquant, avec HTTP 200 :

{
  "jsonrpc": "2.0",
  "error": {
    "code": 13020,
    "message": "not_found",
    "data": {"object": "instrument_name", "value": "BTC-20200101-1-C"}
  },
  "testnet": false,
  "usDiff": 1,
  "usIn": 1791273938274109,
  "usOut": 1791273938274109
}

Basez vos branchements sur la valeur numérique error.code. Les codes JSON-RPC propres au RSM ne font pas partie du catalogue HTTP public par défaut.

Catalogue public des codes d'erreur

Ce catalogue consultable est généré à partir de l'extension info.x-hypercall-error-codes du document OpenAPI public. Il ne contient que les codes HTTP destinés aux utilisateurs et les codes JSON-RPC toujours actifs.

Loading API error catalog…

Liste de contrôle pour le traitement

• Clients HTTP : basez vos branchements sur code, conservez le statut HTTP et respectez Retry-After lorsqu'il est présent.
• Clients d'ordres : traitez status: "REJECTED" comme un résultat d'exécution, même si la requête HTTP a réussi.
• Clients JSON-RPC : basez vos branchements sur la valeur numérique error.code pour le protocole natif de l'endpoint.
• Tous les clients : prévoyez un comportement de repli sûr pour les futurs codes inconnus et n'analysez jamais les messages de diagnostic.