Codes d’erreur

#La forme d’une erreur

Le détail est porté par la clé detail. Sur les erreurs de validation, il nomme la valeur fautive et, lorsqu’une liste finie existe, l’énumère.

{
  "detail": "Symbole 'PEPEUSDT' inconnu. Valeurs acceptees : BTCUSDT, ETHUSDT, ..."
}

Les refus liés à l’offre ont une forme fixe, posée par la passerelle : status, timestamp et detail, plus retry_after sur les refus temporels — également présent dans l’en-tête Retry-After. L’en-tête X-Deny-Reason nomme le motif : rate, quota, family, websocket ou key.

{
  "status": "error",
  "timestamp": 1775648290510,
  "detail": "Debit depasse : votre offre autorise un nombre limite de requetes par minute.",
  "retry_after": 1
}

Le 403 de profondeur est rendu par la route elle-même, sans X-Deny-Reason : son detail commence toujours par « Profondeur d’historique hors offre » et donne le limit maximal utilisable sur ce pas de temps. Les fenêtres par offre sont sur la page Limites d’usage.

#Codes HTTP

#Indicateurs

La validation suit un ordre fixe — pas de temps, nombre de résultats, symbole, analyse des indicateurs, règle de plafond, lecture des bougies — et le premier échec l’emporte. Un corps corrigé peut donc révéler une seconde erreur.

#Flux WebSocket

Toute demande impossible reçoit un message op: error qui dit ce qui était attendu — la liste des symboles valides, celle des canaux, les bornes de depth. Trois situations produisent non pas une erreur mais une fermeture :

La clé est vérifiée au handshake, avant l’ouverture : une clé absente ou invalide, ou une offre sans flux (Free), reçoit un 403 à la poignée de main, avec X-Deny-Reason key ou websocket. Un 429 y signale un rythme d’ouverture trop élevé. Une fois connecté, un canal dont la famille n’est pas dans l’offre reçoit op: error — « canal … hors offre : la famille … n’est pas incluse dans votre abonnement » — et l’abonnement entier est refusé. Voir Limites d’usage.

#Serveur MCP

Les erreurs suivent un motif unique — Erreur (HTTP NNN) : message — pour qu’un agent n’ait qu’un seul cas à reconnaître. Chaque appel d’outil est jugé comme une requête REST avec la clé du client : un 403 de famille hors offre ou un 429 de quota remontent tels quels, avec leur detail. Deux familles lui sont propres :

• Métrique inconnue — le message liste les quarante-six métriques valides.
• Ciblage invalide — deux cibles à la fois, cible manquante, mauvaise cible, ou cible passée à une métrique marché entier. L’erreur nomme le paramètre attendu, et elle est levée avant tout appel réseau.

Un défaut serveur donne lieu à un réessai automatique avant d’être remonté. Un délai dépassé rend Erreur (HTTP 504) après trente secondes.

#Stratégie de reprise

Tout n’est pas rejouable. Rejouer une requête fautive produit exactement la même réponse, et consomme un quota pour rien.

def doit_reessayer(code: int) -> bool:
    """Ce qui est transitoire, et ce qui ne le sera jamais."""
    # 429 et 503 passeront : le serveur dit quand.
    if code in (429, 503):
        return True
    # 500 : un defaut cote service, un reessai a du sens.
    if code == 500:
        return True
    # 400, 403, 422 : la requete est fautive. La rejouer telle quelle
    # produira exactement la meme reponse.
    return False

• Respectez Retry-After plutôt que d’inventer un délai : le serveur sait quand il sera prêt.
• Bornez le nombre de tentatives. Trois ou quatre suffisent : au-delà, le problème n’est pas transitoire.
• Ne rejouez pas un 4xx — hors 429. Corrigez la requête.
• Sur le flux, reconnectez avec un délai croissant, et traitez une fermeture 4003 comme un signal de surcharge côté client : reconnecter sans changer la consommation reproduira la coupure.