Límites de uso de apps y agentes de IA

#Los límites por plan

Cuatro planes, cuatro conjuntos de límites. El plan Empresa se negocia; no tiene valor por defecto.

El catálogo documenta 138 rutas. Tres nunca se descuentan de la cuota, solo se aplica el límite de velocidad: /v1/health, la única que responde sin clave, /v1/limits, los límites de tu clave, y POST /v1/ws/token, el token WebSocket de corta duración (sigue el derecho al flujo). /v1/status cuenta como una petición de precio y volumen. El contrato nombra la familia de cada ruta en x-family.

#Límite de velocidad y cuota mensual

Dos contadores, ambos por cuenta: no por dirección, no por clave. Rotar una clave, o repartir el tráfico entre varias direcciones, no cambia ni uno ni otro. Delante de ellos, el borde aplica un anti-flood por dirección IP: 20 peticiones por segundo, ráfagas de 40, rechazadas con 429 edge_rate_limited y Retry-After: 1. Solo frena las avalanchas: dimensiona en consecuencia una dirección de salida compartida (NAT, serverless).

• El límite de velocidad se mide por minuto, con una ráfaga tolerada: unas cuantas peticiones de golpe pasan; más allá, las siguientes se suavizan y después se rechazan. El rechazo es un 429 rate_limited cuyo Retry-After da los segundos hasta la siguiente petición permitida (el mismo valor que error.details.retry_after_s).
• La cuota mensual cuenta cada petición sujeta a cuota durante el mes natural en UTC, y se reinicia a cero el primer día del mes. Una vez agotada, devuelve un 429 cuyo Retry-After da los segundos que faltan para que se renueve, o hasta un cambio de plan, que es inmediato.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Deny-Reason: rate_limited

{
  "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 cabecera X-Deny-Reason lleva el motivo de cualquier rechazo ligado al plan (rate_limited, quota_exceeded, plan_family, plan_websocket, missing_api_key, invalid_api_key o history_depth), y el cuerpo lo nombra en error.code (rate_limited, quota_exceeded, plan_family, plan_websocket, invalid_api_key, history_depth) con un error.message en inglés. Toda respuesta hecha con una clave contabilizada (cualquier clave creada en la consola) lleva las cabeceras estándar del IETF, en dos políticas: RateLimit-Policy: "rate";q=…;w=…, "quota";q=…;w=… y RateLimit: "rate";r=…;t=…, "quota";r=…;t=…. El r de quota_exceeded es la cuota mensual restante. La consola muestra el mismo estado, y avisa al 80 % y después en la primera petición rechazada.

#Las familias de datos de mercado

Cada endpoint pertenece exactamente a una familia de cuota, y cada plan abre un conjunto de familias. Una familia que falta en tu plan falta en todos los canales: la ruta REST devuelve un 403, el snapshot retira sus campos y los enumera en out_of_plan_fields, el flujo WebSocket rechaza el canal.

HTTP/1.1 403 Forbidden
X-Deny-Reason: plan_family

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "plan_family",
    "message": "The 'options' data family is not included in your plan. GET /v1/limits lists the families of your key; https://bytnode.com/pricing lists the plans that open it."
  }
}

La correspondencia entre las diez categorías del catálogo y estas doce familias de datos de mercado está en la página de precios; la familia de cada ruta está en el catálogo de endpoints y en el contrato (x-family, los identificadores que devuelve GET /v1/limits).

#Hasta dónde llega el historial

La profundidad del historial depende del plan y de la temporalidad. Es una ventana móvil desde ahora, no un límite por petición: ayer está fuera del plan en velas de 1 min en Free, sea cual sea la paginación.

• 30m sigue la ventana de 1h y 1w la de 1d: «Completo» vale por tanto también para la semana allí donde vale para el día.
• Las rutas sin temporalidad (historiales since_ms / until_ms) están limitadas por la ventana 1h del plan: 24 h en Free, 1 semana en Traders, 30 días en Financial, 90 días en Startup. Las series diarias (un punto al día o menos: Fear & Greed, on-chain, ETF, macro) siguen la fila 1d: ilimitadas donde indica «Completo».
• El funding (historiales de la tasa y del acumulado, ventanas de ocho horas, since_ms / until_ms admitidos) sigue la ventana 4h del plan: 1 semana en Free, 30 días en Traders, 72 días en Financial, completo en Startup.
• Las rutas operación por operación (/v1/trades/spot, /v1/trades/futures, /v1/trades/large, /v1/trades-kline/futures/seconds) tienen su propia ventana, la fila ticks de arriba, y solo están abiertas donde lo está la familia: 1 h en Financial, 24 h en Startup. Los campos correspondientes del snapshot (trades_spot, trades_futures, trades_kline_futures_seconds) están limitados en el tiempo por la misma ventana.
• La comprobación se hace sobre el límite más antiguo realmente alcanzado: limit multiplicado por la duración de la temporalidad, o since_ms, o un until_ms que ya va más allá de la ventana.

Superarlo devuelve un 403 explícito, nunca una respuesta truncada: el error.message dice qué se pidió, qué permite el plan y el limit máximo utilizable. Los límites que escribes tú mismo (since_ms, until_ms) tienen una tolerancia de dos minutos para el desfase de reloj; un limit solo, no. Sin limit ni since_ms, no se rechaza nada: la página simplemente se detiene en el borde de la ventana, y next vale null ahí.

HTTP/1.1 403 Forbidden
X-Deny-Reason: history_depth

{
  "status": "error",
  "server_time": "2026-09-30T16:07:27.808Z",
  "error": {
    "code": "history_depth",
    "message": "History depth beyond your plan: 30 day(s) requested on 1h, your plan allows 1 day(s) (i.e. at most limit=24 on this timeframe, and no since_ms/until_ms bound beyond that window).",
    "param": "limit",
    "details": {
      "window_s": 86400,
      "earliest_ms": 1791763200000,
      "max_limit": 24,
      "timeframe": "1h"
    }
  }
}

#Conexiones al flujo

El flujo WebSocket está abierto a partir de Traders. La clave se comprueba en el handshake: un plan sin el flujo recibe un 403 y la conexión no se establece. El límite de conexiones simultáneas vale para toda la cuenta, todas las claves juntas; la conexión de más se cierra con el código 4003 y el límite en el motivo (un cliente demasiado lento se cierra con 4005). Un 503 en el handshake no está ligado a tu plan: dice que el servicio de flujo ha alcanzado su capacidad, para todas las cuentas.

Una conexión que permanece suscrita cuesta mucho menos que consultas repetidas: si llamas al mismo endpoint cada segundo, el flujo es la respuesta adecuada. Ver Flujo WebSocket.

#Límites de profundidad

Con independencia del plan, cada ruta limita su limit. Estos límites son técnicos; la ventana del plan se aplica encima, y cuenta la más estricta de las dos.

#Qué hacer

import time
import httpx  # pip install httpx


def get(client: httpx.Client, path: str, **params):
    """Retry on the delay the server announces, never on a 403."""
    for attempt in range(4):
        response = client.get(path, params=params)

        if response.status_code == 429 and response.headers.get("X-Deny-Reason") == "quota_exceeded":
            # The monthly quota is spent: Retry-After counts the seconds until the 1st
            # of the month. Do not sleep for days: stop, or change plan.
            raise RuntimeError(response.json()["error"]["message"])

        if response.status_code in (429, 503):
            # The server knows when it will be ready: do not invent a delay.
            wait = float(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        body = response.json()
        if body["status"] == "error":
            # 401 / 403 / 422: the request itself is refused (key, plan, value).
            # Replaying it as is produces exactly the same response: keep the
            # stable code, it says what to change.
            raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
        return body

    raise RuntimeError("the service is still unavailable after 4 attempts")

# Three calls where one is enough.
GET /v1/funding/rate?symbol=BTCUSDT
GET /v1/basis?symbol=BTCUSDT
GET /v1/oi/change?symbol=BTCUSDT

# The same result, in one request (from Traders upwards).
GET /v1/snapshot?symbol=BTCUSDT&funding_rate=1&basis=1&oi_change=1