Genesis Arbitrage

Genesis Arbitrage · · 17 min de lectura

Cómo consultar una API de criptomonedas sin superar los límites: ETag, gzip, filtros y reintentos tras un 429

En resumen

  • Una API suele tener tres límites: peticiones por segundo, una cuota de llamadas por periodo y el volumen de descarga. En Genesis API son de 1 a 15 peticiones por segundo, de 500 K a 10 M de llamadas cada 30 días y 60 MB de datos comprimidos cada 10 segundos por clave.
  • Fija el intervalo de polling según meta.freshness_sec: consultar más rápido devuelve el mismo snapshot. If-None-Match convierte una repetición en un 304 gratuito, gzip y los filtros reducen el tráfico, y un único dataset completo en lugar de una petición por moneda ahorra llamadas.
  • Reintenta 429 y 503 tras Retry-After segundos o, sin esa cabecera, con backoff exponencial más jitter aleatorio. Un token bucket en el cliente mantiene tu ritmo por debajo del límite, y las cabeceras X-RateLimit-* y X-Quota-* muestran el margen que queda.

Para consultar una API sin errores 429, ajusta tus peticiones a tres límites a la vez: peticiones por segundo, cuota de llamadas del periodo y volumen de datos que descargas. Cinco técnicas lo cubren: un intervalo no menor que la actualización de los datos, peticiones condicionales con ETag, compresión gzip, filtros en lugar de descargas enormes y reintentos tras la pausa que pide el servidor. Las cifras y el código de abajo son de Genesis API, una API REST de datos del mercado cripto, pero las técnicas sirven para cualquier API HTTP, incluidas las de los exchanges.

Tres límites de una API: peticiones por segundo, cuota y volumen

Un rate limit por segundo detecta las ráfagas: un lote de peticiones enviado de golpe. La cuota detecta tu ritmo medio durante todo el periodo, y el límite de volumen detecta las descargas pesadas aunque haya pocas peticiones.

LímiteQué cuentaGenesis APIAl superarlo
Peticiones por segundoCada petición, incluidos 304 y errores1 en Trial, 2 en Start, 5 en Pro, 15 en Max429 rate_limited, Retry-After: 1
Cuota por periodoSolo las respuestas 200500 K, 2 M, 5 M, 10 M de llamadas cada 30 días429 rate_limited, Retry-After hasta que se restablece la cuota
Volumen de descargaRespuestas comprimidas de 64 KB o más60 MB cada 10 segundos por clave, en todos los planes429 download_limited hasta que termina la ventana

Genesis API nunca cobra las peticiones que superan un límite: un 429 no consume cuota y no cuesta nada. Todas las reglas están en la guía de límites de Genesis API y en la sección Planes y límites de la documentación.

Las API de los exchanges pueden ser más complejas. Binance cuenta el peso de las peticiones por dirección IP, y cada endpoint tiene su propio peso. Un cliente que sigue enviando peticiones tras un 429 recibe un bloqueo automático de IP con el estado 418, y los reincidentes reciben bloqueos más largos (documentación de Binance).

Intervalo de polling: cuántas llamadas gastas en 30 días

Consultar más rápido de lo que se actualizan los datos solo trae repeticiones. El núcleo de Genesis Arbitrage actualiza los datos cada segundo, mientras que la salida de la API para tu plan se actualiza una vez cada meta.freshness_sec segundos: 60 en Trial, 30 en Start, 10 en Pro y 5 en Max. Esa es la frescura de los datos de tu plan y el mínimo para tu intervalo de polling. Genesis API no tiene WebSocket ni webhooks, así que los datos se obtienen haciendo polling por REST.

Ejemplo ilustrativo: un bot en el plan Start — 50 $ al mes, 2 M de llamadas, 2 peticiones por segundo, frescura de 30 s — consulta cuatro endpoints: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread y /market/open-interest.

IntervaloLlamadas en 30 díasParte de la cuota de StartRepeticiones de un snapshot
60 s172 8008,64 %ninguna
30 s345 60017,28 %ninguna
10 s1 036 80051,84 %2 de 3
5 s2 073 600103,68 %5 de 6

Consultar cada 5 segundos agota la cuota el día 29: 4 × 86 400 / 5 = 69 120 llamadas al día, y 2 000 000 / 69 120 ≈ 28,9 días. Cinco de cada seis respuestas repiten un mismo snapshot con el mismo meta.updated_at, y sin If-None-Match cada una cuesta una llamada.

Con una consulta cada 30 segundos, el ritmo medio es 4 / 30 ≈ 0,13 peticiones por segundo. Pero cuatro peticiones enviadas a la vez caen en el mismo segundo, y dos de ellas reciben un 429. Si necesitas datos más frescos que 30 segundos, la respuesta es un plan con un freshness_sec menor: Pro actualiza el snapshot cada 10 segundos, Max cada 5.

Peticiones condicionales: ETag, If-None-Match y 304

Un ETag es una etiqueta de versión de una respuesta. El cliente la guarda y la devuelve en la cabecera If-None-Match de su siguiente petición a la misma URL; si la versión no ha cambiado, el servidor responde 304 Not Modified. Según el RFC 9110, un 304 termina tras las cabeceras y no lleva cuerpo, así que usas tu propia copia de los datos.

En Genesis API un 304 no consume cuota, pero sí ocupa un hueco en el límite de peticiones por segundo. Solo los datasets completos sin filtros reciben etiqueta. Las respuestas a peticiones con coin, exchange, min_spread u otros filtros, así como /orderbooks/book y /orderbooks/coin/{coin}, se construyen por petición y llegan sin ETag.

ETag ahorra cuota donde los datos cambian con menos frecuencia que tus consultas. La etiqueta de los spreads cambia con cada snapshot, así que si consultas una vez por freshness_sec, casi todas las respuestas son un 200.

Ejemplo ilustrativo en Pro: las sumas diarias del análisis de funding, /funding/analytics/daily, se regeneran cada hora; cuando se acumula un año de historial, la sección completa pesa unos 12 MB en gzip, y sin coin se sirve como máximo una vez cada 300 segundos. Consultar cada 300 segundos son 2 592 000 / 300 = 8640 peticiones en 30 días. Con If-None-Match la sección se descarga 30 × 24 = 720 veces, y las otras 8640 − 720 = 7920 respuestas llegan como 304.

El resultado: 720 llamadas en lugar de 8640, y unos 8,6 GB de tráfico en lugar de 104 GB. Las respuestas 304 no cuentan para el límite de descarga completa.

Filtros y coin: qué ahorra llamadas y qué ahorra tráfico

Un filtro reduce la respuesta, pero no el número de llamadas: la cuota cuenta respuestas, y una petición con coin=BTC cuesta lo mismo que el dataset completo. Así que la elección depende de qué se agota primero, las llamadas o el tráfico.

Ejemplo ilustrativo en Start: un bot sigue el funding de cinco monedas. Cinco peticiones a /funding/rates con coin cada 30 segundos suman 5 × 86 400 = 432 000 llamadas en 30 días, además de cinco peticiones por ciclo frente a un límite de 2 por segundo. Un /funding/rates completo con las monedas filtradas en el código cuesta 86 400 llamadas, cinco veces menos, y recibe un ETag.

TareaCómo pedirloQué ahorra
Varias monedas de un datasetDataset completo con If-None-Match, filtro en el códigoLlamadas: una petición en lugar de varias
Una moneda de una sección pesadaEl parámetro coinTráfico y el límite de volumen
Filas por encima de un umbralmin_spread, min_volumeTráfico, pero cada consulta es una llamada
Una sección lenta completaDataset completo con If-None-MatchLlamadas y tráfico

Las secciones más pesadas son las del análisis de funding: el resumen completo pesa unos 600 KB en gzip, los pagos de 7 días unos 1 MB y las sumas diarias hasta 12 MB (endpoints de funding). Un corte de una sola moneda con coin queda fuera del límite de descarga completa, que es de una vez cada 60 segundos para el resumen y los pagos y de una cada 300 para las sumas diarias.

Compresión gzip

La compresión reduce el número de bytes en la red. El cliente la pide con Accept-Encoding: gzip, y el servidor responde con un cuerpo comprimido y una cabecera Content-Encoding: gzip. El requests de Python añade gzip a Accept-Encoding y descomprime la respuesta por sí solo; curl hace lo mismo con --compressed.

En Genesis API la compresión está ligada a un límite: el volumen de descarga se cuenta en datos comprimidos, 60 MB cada 10 segundos por clave, y las respuestas de menos de 64 KB no se cuentan. Los datasets completos y las respuestas grandes llegan en gzip cuando el cliente lo pide (respuestas y errores de Genesis API). Para ver cuántos bytes de cuerpo cruzaron realmente la red, usa la variable size_download de curl:

# bytes del cuerpo en la red con y sin gzip; cada petición es una llamada
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"

Reintentos tras un 429: Retry-After y backoff con jitter

HTTP 429 Too Many Requests es la respuesta del servidor a un cliente que superó un límite. Según el RFC 6585, la respuesta puede llevar una cabecera Retry-After, y según el RFC 9110 su valor es un número de segundos o una fecha. Genesis API envía Retry-After con cada 429 y 503, en segundos.

Un reintento sin pausa casi siempre recibe el mismo error y ocupa otro hueco en la ventana por segundo. Si hay Retry-After, espera lo que pide el servidor. Si no lo hay, espera exponencialmente más tras cada fallo: hasta 1, 2, 4, 8 segundos.

El jitter, una adición aleatoria a la pausa, importa cuando hay muchos clientes: sin él, todos los que recibieron un error en el mismo segundo reintentan también en el mismo segundo. La función backoff elige una pausa aleatoria entre cero y el paso actual y suma una fracción de segundo a Retry-After. fetch reintenta 429, 500 y 503, y se detiene cuando la pausa supera los 10 minutos: así se ve una cuota agotada.

import os
import random
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session()  # reutiliza la conexión TCP, gzip activado
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # path -> (ETag, data): solo datasets completos


def backoff(attempt, retry_after=None, cap=60.0):
    """Pausa antes de un reintento, en segundos."""
    if retry_after and retry_after.isdigit():
        return int(retry_after) + random.uniform(0, 1)
    return random.uniform(0, min(cap, 2 ** attempt))


def fetch(path, params=None, tries=5):
    """GET a la API: devuelve (data, cabeceras de la respuesta)."""
    for attempt in range(tries):
        tag = None if params else cache.get(path, (None,))[0]
        try:
            r = api.get(BASE + path, params=params, timeout=15,
                        headers={"If-None-Match": tag} if tag else {})
        except (requests.ConnectionError, requests.Timeout):
            time.sleep(backoff(attempt))
            continue
        if r.status_code == 304:  # mismo snapshot, sin gastar cuota
            return cache[path][1], r.headers
        if r.status_code in (429, 500, 503):
            wait = backoff(attempt, r.headers.get("Retry-After"))
            if wait > 600:  # así se ve una cuota agotada
                raise RuntimeError(f"la cuota se restablece en {wait:.0f} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403, 404, 410: no reintentar
        data = r.json()["data"]
        if not params and "ETag" in r.headers:
            cache[path] = (r.headers["ETag"], data)
        return data, r.headers
    raise RuntimeError(f"{path}: sin respuesta tras {tries} intentos")
RespuestaPausaReintento
429 rate_limited, por segundoRetry-After: 1 más una fracción de segundoSí
429 rate_limited, cuotaHasta que se restablece la cuota, pueden ser díasNo
429 download_limitedRetry-After, hasta que termina la ventanaSí, con peticiones más acotadas
503 snapshot_not_readyRetry-AfterSí
500, timeout, conexión interrumpidaExponencial con jitterSí
400, 401, 403, 404, 410—No, corrige la petición

Distingues una cuota agotada del límite por segundo por el Retry-After: un segundo frente a horas o días hasta el restablecimiento, con Monthly call quota exceeded. en el cuerpo de la respuesta. Los códigos y cuerpos de error están en la sección Errores de la documentación.

Limitador en el cliente: token bucket

Un reintento resuelve un 429; un limitador en el cliente lo previene. Un token bucket funciona así: los tokens llegan a rate por segundo, cada petición toma uno y, si el cubo está vacío, tienes que esperar. La capacidad, burst, fija cuántas peticiones pueden salir seguidas sin pausa.

import time


class TokenBucket:
    """Como máximo rate peticiones por segundo, hasta burst seguidas."""

    def __init__(self, rate, burst=1):
        self.rate, self.burst = rate, burst
        self.tokens = float(burst)
        self.last = time.monotonic()

    def take(self):
        while True:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens
                              + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return
            time.sleep((1 - self.tokens) / self.rate)

Toma el límite del campo rps_limit de /account/usage (la sección Uso) o de la cabecera X-RateLimit-Limit. Fija el ritmo un poco por debajo del límite, por ejemplo 0.9 * rps_limit: la latencia de red es irregular, así que peticiones enviadas con medio segundo de diferencia pueden llegar al servidor más juntas.

Monitorización: las cabeceras X-RateLimit-* y X-Quota-*

Una respuesta con datos lleva el estado de tus límites: X-RateLimit-Remaining y X-RateLimit-Reset indican lo que queda en la ventana por segundo y cuándo se restablece, mientras que X-Quota-Remaining, X-Quota-Limit y X-Quota-Reset indican la cuota restante, su tamaño y el tiempo unix en que se restablece. Más útil que cualquier resto aislado es el ritmo: qué parte de la cuota se ha gastado en este punto del periodo.

PERIOD = 30 * 86400  # Genesis API cuenta la cuota por 30 días


def watch(h):
    """Comprueba el margen de los límites con las cabeceras de la respuesta."""
    if h.get("X-RateLimit-Remaining") == "0":  # ventana agotada
        reset = float(h.get("X-RateLimit-Reset", 0))
        time.sleep(max(0.0, reset - time.time()))
    try:
        left = int(h["X-Quota-Remaining"])
        limit = int(h["X-Quota-Limit"])
        reset = int(h["X-Quota-Reset"])
    except (KeyError, ValueError):
        return  # las respuestas 429 no llevan cabeceras X-Quota-*
    used = 1 - left / limit
    passed = 1 - (reset - time.time()) / PERIOD
    if used > passed + 0.05:
        print(f"la cuota va por delante: {used:.0%} usado"
              f" con {passed:.0%} del periodo transcurrido")

La función espera a que se restablezca la ventana cuando se agota su límite, y avisa cuando el uso de la cuota va por delante del calendario en más de 5 puntos porcentuales. Ejemplo ilustrativo: el 70 % de la cuota se ha gastado el día 15, así que con el mismo ritmo las llamadas se agotan a los 15 / 0,7 ≈ 21,4 días del periodo. /account/usage da las mismas cifras sin cabeceras: calls_used, calls_limit y period_resets_at.

Un calendario para varios endpoints

Con varios endpoints, cada uno tiene su propio intervalo, y las primeras peticiones se escalonan para que no salgan en lote. Elige el intervalo según la tarea, pero nunca por debajo de freshness_sec: los spreads necesitan el ritmo completo de tu plan, mientras que para muchas estrategias un minuto basta para el funding y el open interest.

import heapq

usage, _ = fetch("/account/usage")  # no gasta una llamada
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])

JOBS = {  # path -> intervalo de polling, s
    "/arbitrage/spot-spot": fresh,
    "/funding/spread": max(fresh, 60),
    "/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
         for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)

while True:
    due, path, every = heapq.heappop(queue)
    time.sleep(max(0.0, due - time.monotonic()))
    bucket.take()
    data, hdrs = fetch(path)
    watch(hdrs)
    print(path, len(data))
    heapq.heappush(queue, (due + every, path, every))

En Start son 86 400 + 43 200 + 43 200 = 172 800 llamadas en 30 días, el 8,64 % de la cuota: spreads cada 30 segundos, funding y open interest cada 60. Las primeras peticiones salen con 30 / 3 = 10 segundos de diferencia, tras lo cual cada endpoint mantiene su propio ritmo, y bucket.take() protege frente a colisiones. Un bot construido sobre este polling, con alertas en Telegram, está en Bot de arbitraje cripto en Python.

Qué hacer ante un 503 y errores del servidor

Según el RFC 9110, 503 Service Unavailable significa una sobrecarga temporal o un mantenimiento, y el servidor puede sugerir una pausa en Retry-After. En Genesis API es 503 snapshot_not_ready: los datos se están reconstruyendo o su fuente se está reiniciando. Reintenta tras Retry-After segundos; la pausa suele ser de unos pocos segundos.

Mientras no hay una respuesta nueva, tu bot sigue teniendo los datos de la última consulta, y esos datos envejecen. Antes de enviar una señal, compara meta.updated_at con la hora actual: un par de un snapshot de hace un minuto puede haber desaparecido ya en el exchange. Otros riesgos se tratan en la lección Riesgos de la automatización.

Reintenta 500 internal_error, timeouts y conexiones interrumpidas con backoff exponencial. Si el error persiste, contacta con soporte con el valor de X-Request-Id, la hora de la petición en UTC, el endpoint y el código de estado. Nunca envíes tu clave.

Preguntas y respuestas

¿Cuántas peticiones por segundo puedo enviar a Genesis API?

Tantas como permita tu plan: 1 en Trial, 2 en Start, 5 en Pro y 15 en Max. El límite es por clave e incluye las respuestas 304 y los errores. El valor de tu plan está en la cabecera X-RateLimit-Limit y en el campo rps_limit de /account/usage.

¿Los errores y las respuestas 304 cuentan para mi cuota?

No. Solo una respuesta 200 consume cuota; 304, 429, 503 y otros errores son gratuitos y no cuestan nada. Eso sí, ocupan huecos en el límite de peticiones por segundo, así que los reintentos sin pausa provocan nuevos 429.

¿Cómo me mantengo por debajo de 60 MB cada 10 segundos?

Activa gzip: el límite cuenta datos comprimidos. Envía If-None-Match con los datasets completos: un 304 no tiene cuerpo. Toma las secciones pesadas, como el análisis de funding, como un corte por coin, y no descargues el mismo dataset completo más a menudo que freshness_sec. Las respuestas de menos de 64 KB no cuentan, y según la documentación, consultar cada dataset con la frescura de tu plan cabe de sobra bajo el límite.

¿Qué significa un error 429 Too Many Requests?

El servidor rechazó la petición porque el cliente superó un límite dentro de una ventana de tiempo. La respuesta puede llevar Retry-After, el número de segundos que hay que esperar; sin él, duplica la pausa tras cada fallo. En Genesis API un 429 viene con el código rate_limited o download_limited.