Respuestas y errores para código y agentes de IA

#El sobre estándar

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

#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.

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

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

#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.

Todas las rutas eliminan la ambigüedad con la clave unavailable: cuando data está vacío (null o una lista vacía), la respuesta dice por qué — tanto en una ruta REST como en cada campo del snapshot. Comprueba unavailable, no si data está vacío:

El detalle de estas claves en el snapshot está en la página Snapshot. Para saber de antemano qué puede servir un activo, consulta su informe de capacidades.

#Los errores

Todo error tiene la misma forma: status: "error", server_time y un objeto error (code, estable y legible por máquina; message, en inglés; param cuando un parámetro es el culpable). Los rechazos ligados al plan llevan también la cabecera X-Deny-Reason, cuyo valor es el error.code (missing_api_key, invalid_api_key, plan_family, plan_websocket, rate_limited, quota_exceeded, history_depth); los rechazos temporales añaden error.details.retry_after_s en el cuerpo y Retry-After como cabecera, con el mismo valor: la espera hasta la próxima petición permitida en el límite de ritmo, los segundos hasta el reinicio en la cuota mensual. Toda respuesta, errores incluidos, lleva una cabecera X-Request-Id: cítala cuando informes de un problema. error.details, presente cuando el error lleva datos estructurados, da lo mismo para el código: suggestion (el valor aceptado más cercano), accepted (los valores aceptados), la ventana de tu plan en 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 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

Toda respuesta hecha con una clave contabilizada (cualquier clave creada en la consola) lleva las cabeceras de límite de velocidad, en el formato estándar del IETF: la política de tu plan y lo que queda de ella, cuota mensual incluida. La consola muestra el mismo estado, y avisa al 80 % y después en la primera petición rechazada. Otras dos cabeceras solo aparecen en un rechazo.