Primeros pasos

Respuestas y errores

Todas las respuestas tienen la misma forma. Esta página describe el sobre, la manera de reducir su tamaño, cómo leer un campo vacío y qué significa cada código de error.

#El sobre estándar

Respuesta

{
  "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"
  }
}

Campo	Tipo	Descripción
`status`	string	ok o error.
`timestamp`	integer	El instante en que se produjo la respuesta, en milisegundos desde la época Unix. Nunca la marca de tiempo del dato.
`data_type`	string	El nombre del tipo devuelto. Permite enrutar una respuesta sin depender de la ruta llamada, útil cuando un cliente pasa por una cola o una caché.
`data`	object \| array \| null	La carga útil. null cuando la métrica no tiene nada que servir en la ventana solicitada.

Dos excepciones que conocer

Tres rutas no pasan por este sobre y sirven su propia forma: /v1/health, /v1/status y POST /v1/indicators, que construye su respuesta por sí misma. Las dos primeras son sondas; la tercera lleva un objeto indicators indexado por tus identificadores.

#Reducir la respuesta

El parámetro ?fields= restringe data a los campos pedidos: una lista separada por comas, con notación de puntos para los campos anidados. En una serie de mil filas de la que solo usas dos columnas, la respuesta se reduce en la misma proporción.

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 campo desconocido se rechaza, con la sugerencia del más cercano en lugar de un silencio:

422

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

#Leer un campo vacío

Un null o una lista vacía no prueba la ausencia del fenómeno: también puede significar que el fenómeno no existe para este activo. Confundir ambos lleva a afirmaciones falsas, como «ninguna liquidación» cuando el activo es una stablecoin, que no tiene mercado de futuros.

El snapshot elimina la ambigüedad con la clave unavailable, presente solo cuando al menos un campo pedido está vacío:

Motivo	Tipo	Descripción
`not_applicable`	structural	La métrica no tiene sentido aquí: un campo derivado del mercado de futuros en una stablecoin spot, u opciones en un activo distinto de BTC y ETH. Ninguna recopilación lo cambiaría.
`no_api_key`	configuration	La fuente de origen no está conectada en esta instalación: el dato nunca se recopiló. Es una carencia de infraestructura, no un hecho de mercado.
`no_data`	market	Una ausencia real de datos en la ventana pedida. El único caso del que se puede sacar una conclusión.

El detalle, con la clave coverage que indica sobre cuántos mercados se construyó una cifra, está en la página Snapshot. Para saber de antemano lo que puede servir un activo, consulta su informe de capacidades.

#Los errores

El detalle de un error lo lleva la clave detail. Los rechazos ligados al plan (límite de velocidad, cuota mensual, familia, flujo, clave) llevan además la cabecera X-Deny-Reason con el motivo; los rechazos temporales añaden retry_after en el cuerpo y Retry-After como cabecera: un segundo en el límite de velocidad, una hora en la cuota mensual.

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

Código	Causa más frecuente	Qué hacer
`400` Petición rechazada	Un símbolo desconocido o desactivado, una profundidad por encima del límite del campo, un parámetro de indicador fuera de rango.	El cuerpo de la respuesta nombra el valor erróneo y, para un símbolo, enumera los aceptados.
`403` Rechazada por el plan o por la clave de API	Cuatro motivos, indicados por la cabecera X-Deny-Reason: clave de API ausente, inválida o revocada (key); familia de datos fuera del plan (family); flujo WebSocket fuera del plan (websocket); o una profundidad de historial más allá de la ventana del plan, cuyo detail empieza por « Profondeur d’historique hors offre ».	En key, comprueba que la cabecera se envía de verdad: algunos clientes HTTP la pierden tras una redirección. En family y websocket, el dato existe pero no está en tu plan. En la profundidad, el detail indica el límite máximo que puedes usar.
`422` Parámetro ausente o mal formado	symbol ausente, temporalidad fuera de la lista, campo multitemporalidad solicitado sin el sufijo @tf, campo desconocido en ?fields=, cuerpo JSON no válido.	En ?fields=, la respuesta sugiere el campo más parecido. En una temporalidad, enumera los valores aceptados.
`429` Velocidad o cuota superada	O más peticiones por minuto de las que permite tu plan, o una ráfaga demasiado densa (X-Deny-Reason: rate, Retry-After: 1); o la cuota mensual de la cuenta está agotada (X-Deny-Reason: quota, Retry-After: 3600).	En rate, espera el segundo que indica Retry-After. En quota, el contador se reinicia el primer día del mes (UTC); también puedes cambiar de plan desde la consola.
`503` Indisponibilidad momentánea	Una dependencia de lectura se está recuperando, o se ha alcanzado el límite de conexiones simultáneas del flujo.	Reinténtalo tras el plazo que indica Retry-After. El error es transitorio por naturaleza.
`500` Error inesperado	Un fallo del servicio, nunca causado por la petición.	Reinténtalo; si la respuesta persiste, notifícala con la marca de tiempo que lleva la respuesta.

La página Códigos de error repasa cada caso con los mensajes exactos y los errores propios de los indicadores y del flujo en tiempo real.

#Cabeceras de respuesta

No hay cabecera de contador en las respuestas normales: el estado de la cuota se sigue en la consola, que avisa al 80 % y después en la primera petición rechazada. Solo aparecen dos cabeceras en un rechazo.

Cabecera	Tipo	Descripción
`X-Deny-Reason`	string	El motivo de un rechazo ligado al plan: rate (límite de velocidad), quota (cuota mensual), family (familia fuera del plan), websocket (flujo fuera del plan) o key (clave ausente, inválida o revocada).
`Retry-After`	integer	Presente en 429 y en 503. El número de segundos que esperar antes de reintentar: 1 si se supera el límite de velocidad, 3600 si la cuota mensual está agotada. Respétalo en lugar de inventar un plazo.