Codes d’erreur

#La forme d’une erreur

Toute erreur a une seule forme, quelle que soit la couche qui refuse (passerelle, service ou validation) : status: "error", server_time et un objet error avec un code stable, un message en anglais et, quand un paramètre est en cause, param. error.details, un objet présent quand l’erreur porte des données structurées, donne les mêmes choses pour le code : suggestion, accepted, la fenêtre de votre offre sur un history_depth, retry_after_s sur les refus temporels. Rien n’est posé à côté d’error.

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "invalid_symbol",
    "message": "Unknown symbol 'BTCUSD'. Did you mean 'BTCUSDT'? Accepted values: ADAUSDT, AVAXUSDT, BNBUSDT, BTCUSDT, DOGEUSDT, ETHUSDT, GRAMUSDT, HBARUSDT, HYPEUSDT, LINKUSDT, LTCUSDT, NEARUSDT, SOLUSDT, SUIUSDT, TAOUSDT, TRXUSDT, UNIUSDT, USDCUSDT, USDTUSDC, XLMUSDT, XMRUSDT, XRPUSDT.",
    "param": "symbol",
    "details": {
      "suggestion": "BTCUSDT",
      "accepted": [
        "ADAUSDT",
        "AVAXUSDT",
        "BNBUSDT",
        "BTCUSDT",
        "DOGEUSDT",
        "ETHUSDT",
        "GRAMUSDT",
        "HBARUSDT",
        "HYPEUSDT",
        "LINKUSDT",
        "LTCUSDT",
        "NEARUSDT",
        "SOLUSDT",
        "SUIUSDT",
        "TAOUSDT",
        "TRXUSDT",
        "UNIUSDT",
        "USDCUSDT",
        "USDTUSDC",
        "XLMUSDT",
        "XMRUSDT",
        "XRPUSDT"
      ]
    }
  }
}

Les refus liés à l’offre ont la même forme, plus error.details.retry_after_s 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_limited, quota_exceeded, plan_family, plan_websocket, missing_api_key, invalid_api_key ou history_depth.

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: your plan allows a limited number of requests per minute. Retry after the Retry-After delay.",
    "details": {
      "retry_after_s": 2
    }
  }
}

Le 403 de profondeur porte X-Deny-Reason: history_depth et error.code: history_depth, comme les autres refus liés à l’offre ; son message donne la limit maximale utilisable sur cette unité de temps. Les fenêtres par offre sont sur la page Limites d’usage.

const response = await fetch(url, { headers: { "X-API-KEY": key } });
const body = await response.json();

if (body.status === "error") {
  switch (body.error.code) {
    case "rate_limited":
    case "service_unavailable":
      // Transient: wait Retry-After seconds, then retry.
      break;
    case "history_depth":
      // Ask for less history, or upgrade: error.message gives the max limit.
      break;
    case "invalid_symbol":
    case "unknown_parameter":
      // Fix the request: error.param names the culprit, error.message the fix.
      break;
    default:
      throw new Error(body.error.code + ": " + body.error.message);
  }
}

#Codes HTTP

#Indicateurs

La validation suit un ordre fixe (timeframe, limit, symbole, lecture des indicateurs, règle du 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 reçoit un 401 missing_api_key, une clé inconnue ou révoquée un 401 invalid_api_key (avec WWW-Authenticate), une offre sans le flux (Free) un 403 plan_websocket — à chaque fois la valeur de X-Deny-Reason. Un 429 y signale un rythme d’ouverture trop élevé, et un 503 un service de flux qui a atteint sa capacité, tous comptes confondus : réessayez un peu plus tard. Une fois connecté, un canal dont la famille n’est pas dans l’offre reçoit op: error avec error.code: plan_family et tout l’abonnement est refusé. Voir Limites d’usage.

#Serveur MCP

Les erreurs suivent un seul modèle, Error (HTTP NNN): message [code: …], et un appel d’outil en échec est signalé comme une erreur MCP (isError), avec la même erreur dans structuredContent.error : status, code, message, et param, hint, retry_after_s quand ils s’appliquent. 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 message et leur error.code. Deux familles lui sont propres :

• Requête invalide : champ inconnu, cible manquante (symbol, asset, series) ou qu’aucun champ demandé n’attend, paramètre que la route choisie n’accepte pas, timeframe qu’aucun champ n’utilise, fenêtre datée sur un champ qui n’en a pas. Tout est listé dans un seul message, avant tout appel réseau.
• Réponse partielle : dans les cinq outils de données MCP (get_pair_data, get_options_data…), un champ en erreur n’empêche pas les autres. Il est signalé sous errors et la réponse porte partial: true ; l’appel n’échoue que si aucun champ n’aboutit.

Une relance n’a lieu que si l’amont n’a pas répondu (502, 503, 504 ou panne réseau) : un 500 n’est pas rejoué, car chaque requête compte dans le quota du client. Un délai dépassé renvoie Error (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.

import httpx  # pip install httpx


def should_retry(response: httpx.Response) -> bool:
    """What is transient, and what never will be (the official SDKs do the same)."""
    # A spent monthly quota only resets on the 1st of the month: fail fast.
    if response.status_code == 429 and response.headers.get("X-Deny-Reason") == "quota_exceeded":
        return False
    # 429 (rate) and 503: the server says when, in Retry-After. 502 and 504:
    # a gateway hiccup or a slow query. Retry with an increasing delay.
    if response.status_code in (429, 502, 503, 504):
        return True
    # 500: a fault on the service side, retry once.
    if response.status_code == 500:
        return True
    # 401, 403, 404, 405, 422: the request is at fault. Replaying it as is
    # produces 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 lisez le code de fermeture : 4003, le plafond de l’offre est atteint, une autre connexion du compte doit d’abord se fermer ; 4005 (client too slow), le client est surchargé, et se reconnecter sans changer la consommation reproduira la coupure. Un 503 à la poignée de main demande seulement d’attendre.