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, quand 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 (aussi présent dans l’en-tête Retry-After). L’en-tête X-Deny-Reason nomme la raison : 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 renvoyé par la route elle-même, sans X-Deny-Reason : son detail commence toujours par « Profondeur d’historique hors offre » et donne la limit maximale utilisable sur cette unité de temps. Les fenêtres par offre sont sur la page Limites d’usage.

#Codes HTTP

#Indicateurs

La validation suit un ordre fixe (unité 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 à la poignée de main, avant l’ouverture : une clé absente ou invalide, ou une offre sans le flux (Free), reçoit un 403 à la poignée de main, avec X-Deny-Reason key ou websocket. Un 429 à ce moment-là 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 tout l’abonnement est refusé. Voir Limites d’usage.

#Serveur MCP

Les erreurs suivent un seul modèle, Erreur (HTTP NNN) : message, pour qu’un agent n’ait qu’un cas à reconnaître. Chaque appel d’outil est jugé comme une requête REST avec la clé du client : un 403 pour une famille hors offre ou un 429 pour le quota reviennent 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 une cible passée à une métrique de tout le marché. L’erreur nomme le paramètre attendu, et elle est levée avant tout appel réseau.

Une panne du serveur donne lieu à une nouvelle tentative automatique avant d’être signalée. Un délai dépassé renvoie Erreur (HTTP 504) après trente secondes.

#Stratégie de nouvelle tentative

Tout ne se rejoue pas. Rejouer une requête fautive produit exactement la même réponse, et consomme du quota pour rien.

def should_retry(code: int) -> bool:
    """What is transient, and what never will be."""
    # 429 and 503 will pass: the server says when.
    if code in (429, 503):
        return True
    # 500: a fault on the service side, a retry makes sense.
    if code == 500:
        return True
    # 400, 403, 422: the request is at fault. Replaying it as is will
    # produce exactly the same response.
    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 passager.
• Ne rejouez pas un 4xx, 429 mis à part. Corrigez la requête.
• Sur le flux, reconnectez-vous avec un délai croissant, et traitez une fermeture 4003 comme le signal d’une surcharge côté client : se reconnecter sans changer la consommation reproduira la coupure.