Límites de uso

#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 121 rutas, dos de las cuales son sondas fuera de cuota (/v1/health y /v1/status) que no cuentan para nadie. Solo la primera responde sin clave.

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

• 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 con Retry-After: 1.
• 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 con Retry-After: 3600 hasta que se renueva, o hasta un cambio de plan, que es inmediato.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-Deny-Reason: rate

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

La cabecera X-Deny-Reason lleva el motivo de cualquier rechazo ligado al plan (rate, quota, family, websocket o key), y el cuerpo lo repite en claro en detail. No hay cabecera de contador en las respuestas normales: el estado de la cuota se consulta en la consola, que avisa al 80 % y después en la primera petición rechazada.

#Las familias de datos

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: family

{"status":"error","timestamp":1775648290510,"detail":"Cette famille de donnees n est pas incluse dans votre offre."}

La correspondencia entre las trece familias del catálogo y estas doce familias de cuota está en la página de precios; la que hay entre una ruta y su familia está en el catálogo de endpoints.

#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, series diarias, funding) 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 rutas tick a tick (/v1/raw/spot-ticks, /v1/raw/futures-ticks, /v1/raw/trades) 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.
• 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 detail dice qué se pidió, qué permite el plan y el limit máximo utilizable.

HTTP/1.1 403 Forbidden

{"detail":"Profondeur d'historique hors offre : 30 jour(s) demandes en 1m, votre offre en autorise 1 heure(s) (soit limit=60 au maximum sur ce timeframe, et aucune borne since_ms/until_ms au-dela de cette fenetre)."}

#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, sumando todas las claves; la conexión que sobra se cierra con el código 4003 y el límite en el motivo.

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


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 in (429, 503):
            # The server knows when it will be ready: do not invent a delay.
            # On an exhausted monthly quota (X-Deny-Reason: quota), Retry-After
            # is an hour: no point insisting, the counter restarts on the 1st.
            wait = float(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        # 403: the request is outside the plan (family, depth, key). Replaying
        # it as is will produce exactly the same response.
        response.raise_for_status()
        return response.json()

    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/delta?symbol=BTCUSDT

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