Prise en main

Réponses et erreurs

Toutes les réponses ont la même forme. Cette page décrit l’enveloppe, la façon d’en réduire la taille, la lecture d’un champ vide, et ce que signifie chaque code d’erreur.

#L’enveloppe standard

Réponse

{
  "status": "ok",
  "timestamp": 1775648290510,
  "data_type": "basis",
  "data": {
    "basis_value": 42.18,
    "basis_pct": 0.059,
    "futures_price": 71462.51,
    "spot_price": 71420.33,
    "timestamp": "2026-08-29T11:38:00+00:00"
  }
}

Champ	Type	Description
`status`	string	ok ou error.
`timestamp`	integer	L’instant où la réponse a été produite, en millisecondes depuis l’époque Unix. Jamais l’horodatage de la donnée.
`data_type`	string	Le nom du type retourné. Il permet de router une réponse sans se fier au chemin appelé — utile quand un client passe par une file ou un cache.
`data`	object \| array \| null	La charge utile. null quand la métrique n’a rien à servir sur la fenêtre demandée.

Deux exceptions à connaître

Trois routes ne passent pas par cette enveloppe et servent leur propre forme : /v1/health, /v1/status et POST /v1/indicators, qui construit lui-même sa réponse. Les deux premières sont des sondes, la troisième porte un objet indicators indexé par vos identifiants.

#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 l’imbriqué. Sur une série de mille lignes dont vous n’exploitez que deux colonnes, la réponse fond d’autant.

curl

# La reponse complete
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT"

# Deux champs seulement
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=BTCUSDT&fields=basis_pct,timestamp"

# Notation pointee pour un champ imbrique
curl -H "X-API-KEY: $BYTNODE_KEY" \
  "https://api.bytnode.com/v1/options/summary?asset=BTC&fields=open_interest.total_usd"

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

422

{
  "detail": "Champ inconnu : 'basis_percent'. Vouliez-vous dire 'basis_pct' ?"
}

#Lire un champ vide

Un null ou une liste vide ne prouve pas l’absence du phénomène : il peut aussi bien signifier que le phénomène n’existe pas pour cet actif. Confondre les deux conduit à des affirmations fausses — « aucune liquidation » alors qu’il s’agit d’un stablecoin, qui n’a pas de marché à terme.

Le snapshot lève l’ambiguïté avec la clé unavailable, présente uniquement lorsqu’au moins un champ demandé est vide :

Raison	Type	Description
`not_applicable`	structurel	La métrique n’a pas de sens ici : un champ dérivé du marché à terme sur un stablecoin spot, ou les options sur un actif autre que BTC et ETH. Aucune collecte n’y changerait rien.
`no_api_key`	configuration	La source amont n’est pas branchée sur cette installation : la donnée n’a jamais été collectée. C’est un trou d’infrastructure, pas un fait de marché.
`no_data`	marché	Réelle absence de donnée sur la fenêtre demandée. Le seul cas dont on puisse tirer une conclusion.

Le détail, avec la clé coverage qui dit sur combien de places un chiffre a été construit, se lit sur la page Snapshot. Pour savoir à l’avance ce qu’un actif peut servir, interrogez son rapport de capacité.

#Les erreurs

Le détail d’une erreur est porté par la clé detail. Les refus liés à l’offre — débit, quota mensuel, famille, flux, clé — portent en plus l’en-tête X-Deny-Reason avec le motif ; les refus temporels ajoutent retry_after dans le corps et Retry-After en en-tête : une seconde sur le débit, une heure sur le quota mensuel.

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

Code	Cause la plus fréquente	Ce qu’il faut faire
`400` Requête refusée	Un symbole inconnu ou désactivé, une profondeur au-delà du plafond du champ, un paramètre d’indicateur hors bornes.	Le corps de la réponse nomme la valeur fautive et, pour un symbole, liste celles qui sont acceptées.
`403` Refusé par l’offre ou par la clé	Quatre motifs, nommés par l’en-tête X-Deny-Reason : clé absente, invalide ou révoquée (key) ; famille de données hors offre (family) ; flux WebSocket hors offre (websocket) ; ou une profondeur d’historique au-delà de la fenêtre de l’offre, dont le detail commence par « Profondeur d’historique hors offre ».	Sur key, vérifiez que l’en-tête est bien transmis : certains clients HTTP le suppriment après une redirection. Sur family et websocket, la donnée existe mais n’est pas dans votre offre. Sur la profondeur, le detail donne le limit maximal à utiliser.
`422` Paramètre manquant ou mal formé	symbol absent, timeframe hors liste, champ multi-timeframe demandé sans suffixe @tf, champ inconnu dans ?fields=, corps JSON invalide.	Sur ?fields=, la réponse propose le champ le plus proche. Sur un timeframe, elle liste les valeurs acceptées.
`429` Débit ou quota dépassé	Soit plus de requêtes par minute que votre offre n’en autorise, ou une rafale trop dense (X-Deny-Reason: rate, Retry-After: 1) ; soit le quota mensuel du compte épuisé (X-Deny-Reason: quota, Retry-After: 3600).	Sur rate, attendez la seconde indiquée par Retry-After. Sur quota, le compteur repart au premier jour du mois (UTC) — ou changez d’offre depuis la console.
`503` Indisponibilité momentanée	Une dépendance de lecture est en cours de reprise, ou le plafond de connexions simultanées du flux est atteint.	Réessayez après le délai porté par Retry-After. L’erreur est transitoire par construction.
`500` Erreur inattendue	Un défaut côté service, jamais causé par la requête.	Réessayez ; si la réponse persiste, signalez-la avec l’horodatage porté par la réponse.

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

Il n’y a pas d’en-tête de compteur sur les réponses normales : l’état du quota se suit dans la console, qui prévient à 80 % puis à la première requête refusée. Deux en-têtes n’apparaissent que sur un refus.

En-tête	Type	Description
`X-Deny-Reason`	string	Le motif d’un refus lié à l’offre : rate (débit), quota (quota mensuel), family (famille hors offre), websocket (flux hors offre) ou key (clé absente, invalide ou révoquée).
`Retry-After`	integer	Présent sur 429 et sur 503. Le nombre de secondes à attendre avant de réessayer — 1 sur un débit dépassé, 3600 sur un quota mensuel épuisé. Respectez-le plutôt que d’inventer un délai.