Premiers pas

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, comment lire un champ vide, et ce que veut dire 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 renvoyé. Il permet d’aiguiller une réponse sans dépendre du 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 sa réponse lui-même. 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 les champs imbriqués. Sur une série de mille lignes dont vous n’utilisez que deux colonnes, la réponse diminue d’autant.

curl

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

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

# Dotted notation for a nested field
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 la 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 : 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.

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

Raison	Type	Description
`not_applicable`	structural	La métrique n’a pas de sens ici : un champ dérivé du marché à terme sur un stablecoin spot, ou des options sur un autre actif 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 manque d’infrastructure, pas un fait de marché.
`no_data`	market	Une vraie absence de données sur la fenêtre demandée. Le seul cas dont on peut tirer une conclusion.

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

#Les erreurs

Le détail d’une erreur est porté par la clé detail. Les refus liés à l’offre (limite de débit, quota mensuel, famille, flux, clé) portent aussi l’en-tête X-Deny-Reason avec la raison ; les refus temporels ajoutent retry_after dans le corps et Retry-After en en-tête : une seconde sur la limite de 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	Que 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 ceux qui sont acceptés.
`403` Refusé par l’offre ou par la clé d’API	Quatre raisons, nommées par l’en-tête X-Deny-Reason : clé d’API 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 envoyé : certains clients HTTP le perdent 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 la limite maximale à utiliser.
`422` Paramètre manquant ou mal formé	symbol manquant, unité de temps hors liste, champ multi-unités demandé sans le suffixe @tf, champ inconnu dans ?fields=, corps JSON invalide.	Sur ?fields=, la réponse suggère le champ le plus proche. Sur une unité de temps, elle liste les valeurs acceptées.
`429` Débit ou quota dépassé	Soit plus de requêtes par minute que votre offre ne l’autorise, ou une rafale trop dense (X-Deny-Reason: rate, Retry-After: 1) ; soit le quota mensuel du compte est épuisé (X-Deny-Reason: quota, Retry-After: 3600).	Sur rate, attendez la seconde indiquée par Retry-After. Sur quota, le compteur repart le premier jour du mois (UTC) ; vous pouvez aussi changer d’offre depuis la console.
`503` Indisponibilité momentanée	Une dépendance de lecture redémarre, 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	Une panne côté service, jamais causée 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	La raison d’un refus lié à l’offre : rate (limite de 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 une limite de débit dépassée, 3600 sur un quota mensuel épuisé. Respectez-le plutôt que d’inventer un délai.