Réponses et erreurs pour le code et les agents IA

#L’enveloppe standard

{
  "status": "ok",
  "server_time": "2026-10-10T08:51:22.927Z",
  "data_type": "basis",
  "symbol": "BTCUSDT",
  "data": {
    "time": "2026-10-10T08:51:14.104Z",
    "basis_value": -42.0048049747,
    "basis_pct": -0.0507185886791,
    "futures_price": 82776.0067294,
    "spot_price": 82818.0115344
  }
}

#Réduire la réponse

Le paramètre ?fields= restreint data aux champs demandés : une liste séparée par des virgules, en notation pointée pour les champs imbriqués. Sur une série de mille lignes dont vous n’utilisez que deux colonnes, la réponse diminue d’autant.

# The full response
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT"

# Two fields only
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT&fields=time,basis_pct"

# Dotted notation for a nested field
curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/btc/network?fields=difficulty,next_adjustment.estimated_retarget_at"

Un champ inconnu est refusé, avec la suggestion du plus proche plutôt qu’un silence :

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "unknown_field",
    "message": "Unknown field 'basis_percent'. Did you mean 'basis_pct'? Accepted fields: basis_pct, basis_value, futures_price, spot_price, time.",
    "param": "fields",
    "details": {
      "suggestion": "basis_pct",
      "accepted": [
        "basis_pct",
        "basis_value",
        "futures_price",
        "spot_price",
        "time"
      ]
    }
  }
}

#Lire un champ vide

Un null ou une liste vide ne prouve pas l’absence du phénomène : cela peut tout aussi bien vouloir dire que le phénomène n’existe pas pour cet actif. Confondre les deux mène à des affirmations fausses, comme « aucune liquidation » alors que l’actif est un stablecoin, qui n’a pas de marché à terme.

Chaque route lève l’ambiguïté avec la clé unavailable : quand data est vide (null ou une liste vide), la réponse dit pourquoi — sur une route REST comme sur chaque champ du snapshot. Testez unavailable, pas le vide de data :

Le détail de ces clés sur le snapshot est sur la page Snapshot. Pour savoir à l’avance ce qu’un actif peut servir, interrogez son rapport de capacités.

#Les erreurs

Toute erreur a la même forme : status: "error", server_time et un objet error (code, stable et lisible par une machine ; message, en anglais ; param quand un paramètre est en cause). Les refus liés à l’offre portent aussi l’en-tête X-Deny-Reason, dont la valeur est l’error.code (missing_api_key, invalid_api_key, plan_family, plan_websocket, rate_limited, quota_exceeded, history_depth) ; les refus temporels ajoutent error.details.retry_after_s dans le corps et Retry-After en en-tête, avec la même valeur : l’attente jusqu’à la prochaine requête permise sur le débit, les secondes jusqu’à la remise à zéro sur le quota mensuel. Toute réponse, erreurs comprises, porte un en-tête X-Request-Id : citez-le quand vous signalez un problème. error.details, présent quand l’erreur porte des données structurées, donne les mêmes choses pour le code : suggestion (la valeur acceptée la plus proche), accepted (les valeurs acceptées), la fenêtre de votre offre sur un 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
    }
  }
}

La page Codes d’erreur reprend chaque cas avec les messages exacts et les erreurs propres aux indicateurs et au flux temps réel.

#En-têtes de réponse

Toute réponse faite avec une clé comptée (toute clé créée dans la console) porte les en-têtes de débit, au format standard de l’IETF : la politique de votre offre et ce qu’il en reste, quota mensuel compris. La console montre le même état, et prévient à 80 % puis à la première requête refusée. Deux autres en-têtes n’apparaissent que sur un refus.