Límites de Genesis API: cuota de llamadas, peticiones por segundo, frescura de datos y errores 429
En resumen
- Tu plan fija la cuota de llamadas por 30 días (de 500.000 en Trial a 10 millones en Max), el límite de peticiones por segundo (de 1 a 15) y la frescura de los datos (de 60 a 5 segundos).
- Solo una respuesta
200consume cuota. Las respuestas304y los errores no cuestan nada, pero ocupan un hueco en el límite de peticiones por segundo; al superar un límite el servidor devuelve429y no cobra nada. - Consultar más rápido que
meta.freshness_secno aporta datos nuevos: tu plan recibe una instantánea nueva una vez por ese intervalo, yIf-None-Matchconvierte las consultas sobrantes en respuestas304gratuitas.
Los límites de Genesis API son cuatro topes por clave: la cuota de llamadas para un periodo de 30 días, el rate limit en peticiones por segundo, la frescura de los datos y el volumen de descarga. Tu plan fija los tres primeros; el volumen de descarga es igual para todos: 60 MB de datos comprimidos cada 10 segundos. Al superar cualquier límite, el servidor devuelve un error 429 y no cobra nada.
Límites por plan
| Plan | Llamadas por 30 días | Peticiones por segundo | Frescura |
|---|---|---|---|
| Trial, $20/mes | 500.000 | 1 | 60 s |
| Start, $50/mes | 2.000.000 | 2 | 30 s |
| Pro, $100/mes | 5.000.000 | 5 | 10 s |
| Max, $200/mes | 10.000.000 | 15 | 5 s |
La frescura de los datos es el intervalo con el que tu plan recibe una instantánea nueva: cada 60 segundos en Trial, cada 5 en Max. Las respuestas la incluyen en el campo meta.freshness_sec. Pagar 3 meses ahorra un 10 %, y 6 meses, un 20 %. La comparativa de planes está en la página de precios de Genesis API, y las reglas, en la sección Planes y límites de la documentación.
Qué consume la cuota
Una llamada es una respuesta 200. Las respuestas 304 (datos sin cambios) y los errores 4xx y 5xx no consumen cuota, pero cuentan para el límite de peticiones por segundo. Una petición a /account/usage no consume ninguna llamada.
La cuota cubre un periodo de 30 días, no un mes natural. La hora del reinicio aparece en la cabecera X-Quota-Reset, en el campo period_resets_at y en la línea «resets …» de tu perfil. Cuando la cuota se agota, el servidor responde 429 rate_limited, y Retry-After indica los segundos que faltan hasta el reinicio, que pueden ser días.
Cabeceras de rate limit
La respuesta de un endpoint de datos incluye el estado de tus límites (valores ilustrativos):
| Cabecera | Ejemplo | Qué muestra |
|---|---|---|
X-RateLimit-Limit | 5 | Límite de peticiones por segundo de tu plan |
X-RateLimit-Remaining | 4 | Peticiones restantes en la ventana actual |
X-RateLimit-Reset | 1785200001 | Hora Unix en que se reinicia la ventana |
X-Quota-Limit | 5000000 | Cuota de llamadas del periodo de 30 días |
X-Quota-Remaining | 4815799 | Llamadas restantes en el periodo |
X-Quota-Reset | 1786492800 | Hora Unix en que se reinicia la cuota |
Retry-After | 1 | Segundos de espera antes de reintentar, en 429 y 503 |
La ventana de peticiones por segundo dura un segundo, así que en una respuesta normal X-RateLimit-Reset apunta al inicio del segundo siguiente. La cuota restante del ejemplo: 5.000.000 − 184.201 = 4.815.799 llamadas, las mismas cifras que devuelve /account/usage.
El endpoint /account/usage
curl "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"success": true,
"data": {
"plan": "pro",
"calls_used": 184201,
"calls_limit": 5000000,
"rps_limit": 5,
"freshness_sec": 10,
"period_resets_at": 1786492800
},
"meta": { … }
}
| Campo | Tipo | Significado |
|---|---|---|
plan | string | Plan: trial, start, pro o max |
calls_used | int | Llamadas usadas en el periodo actual |
calls_limit | int | Cuota de llamadas por periodo |
rps_limit | int | Límite de peticiones por segundo |
freshness_sec | int | Retraso de los datos, en segundos |
period_resets_at | int | Hora Unix en que se reinicia la cuota |
El endpoint está disponible en todos los planes y se describe en la sección Uso. Llámalo al iniciar un bot, para comprobar el plan y la cuota restante antes de empezar a consultar.
Errores 429: rate_limited y download_limited
| Respuesta | Cuándo aparece | Qué hacer |
|---|---|---|
429 rate_limited | Más peticiones por segundo de las que permite tu plan | Esperar el tiempo de Retry-After y espaciar las peticiones |
429 rate_limited | La cuota del periodo está agotada | Esperar al reinicio o cambiar de plan |
429 rate_limited | Descarga completa de analítica de funding antes de lo permitido | Pedir una porción con coin o enviar If-None-Match |
429 download_limited | Más de 60 MB de datos comprimidos en 10 segundos | Esperar el tiempo de Retry-After y acotar la petición con filtros |
El código de estado 429 Too Many Requests está definido en la RFC 6585, donde Retry-After es opcional. Genesis API lo envía con cada 429, siempre en segundos.
Las respuestas de menos de 64 KB no cuentan para el volumen de descarga, y consultar todos los conjuntos de datos con la frescura de tu plan cabe en el límite con holgura. Las descargas completas de analítica de funding sin coin tienen su propio límite: /funding/analytics/summary y /funding/analytics/recent una vez cada 60 segundos, /funding/analytics/daily una vez cada 300 segundos por clave. Las peticiones con coin y las respuestas 304 no tienen límite; los detalles están en la sección Analítica de funding.
Acceso por plan y 403 plan_restricted
| Plan | Qué incluye |
|---|---|
| Trial | Arbitraje CEX (Spot – Spot, Spot – Futuros, Futuros – Futuros), tasas de financiación (funding) y spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, señales de IA, búsqueda de monedas, /account/usage |
| Start | Todo lo de Trial, más acciones /arbitrage/stocks, secciones on-chain /onchain/{section}, arbitraje de mercados de predicción en los modos exact y dutch, estado de las plataformas |
| Pro y Max | Todos los endpoints: DEX – Spot, DEX – Futuros, Crosschain, DEX Dumps, libros de órdenes, analítica de funding, analítica de mercados de predicción, smart money, operaciones, traders, los modos llm y sport, swaps DEX, analítica OnChain y moneda |
Un endpoint fuera de tu plan devuelve 403, y lo mismo ocurre con una petición mode=sport a /predictions/arbitrage en Start:
{
"success": false,
"error": {
"code": "plan_restricted",
"message": "This endpoint is not included in your plan."
}
}
Un 403 no consume cuota. Reintentarlo no sirve de nada: solo un plan superior abre el acceso.
Cómo dimensionar el plan según tu carga
Ejemplo ilustrativo: un bot consulta tres endpoints, /arbitrage/spot-spot, /funding/spread y /market/open-interest, cada 10 segundos las 24 horas.
- Peticiones por segundo: 3 / 10 = 0,3 de media. Si las tres salen a la vez, caen en el mismo segundo, y Trial y Start devuelven
429para las sobrantes. - Llamadas por día: 86.400 / 10 = 8.640 consultas, 8.640 × 3 = 25.920 llamadas.
- Llamadas por 30 días: 25.920 × 30 = 777.600. Es más que la cuota de Trial, de 500.000; en Start son 777.600 / 2.000.000 = 38,88 % de la cuota.
- Frescura: en Start la instantánea se actualiza cada 30 segundos, es decir, 86.400 / 30 = 2.880 veces al día. Los datos nuevos salen de 2.880 × 3 × 30 = 259.200 llamadas, y las otras 777.600 − 259.200 = 518.400 devuelven lo mismo.
El mismo bot consultando con la frescura de cada plan:
| Frescura y consulta | Llamadas por 30 días | Plan | Parte de la cuota |
|---|---|---|---|
| Cada 60 s | 129.600 | Trial | 26 % |
| Cada 30 s | 259.200 | Start | 13 % |
| Cada 10 s | 777.600 | Pro | 16 % |
| Cada 5 s | 1.555.200 | Max | 16 % |
Consultar cada 10 segundos tiene sentido desde Pro: 777.600 / 5.000.000 = 15,552 % de la cuota, y el límite de 5 peticiones por segundo permite enviar las tres a la vez. Si el bot admite datos con 30 segundos de antigüedad, Start con consulta cada 30 segundos cuesta 259.200 / 2.000.000 = 12,96 % de la cuota.
Consultar sin llamadas desperdiciadas: ETag y Retry-After
Tu plan recibe una instantánea nueva cada meta.freshness_sec segundos, y consultar más rápido devuelve la misma instantánea con el mismo meta.updated_at. Sin la cabecera If-None-Match, esa respuesta es un 200 y una llamada gastada. Con ella, el servidor responde 304 sin cuerpo: la cuota queda intacta, pero se ocupa un hueco del límite por segundo.
Un ETag no viene en todas las respuestas. Lo devuelven los conjuntos de datos completos, es decir, las peticiones sin filtros, como /funding/spread en el ejemplo siguiente. Una respuesta filtrada (coin, min_spread y otros) no lleva ETag, y cada consulta cuesta una llamada: los filtros ahorran tráfico, el ETag ahorra cuota. Los reintentos y la compresión se explican en cómo consultar una API de forma eficiente y en la guía de respuestas y errores.
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30
while True:
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
r = requests.get(URL, headers=headers, timeout=15)
if r.status_code in (429, 500, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 600: # la cuota está agotada, paramos aquí
raise SystemExit(f"Cuota agotada, se reinicia en {wait} s")
time.sleep(wait)
continue
r.raise_for_status() # un reintento no arregla 401 ni 403
left = r.headers.get("X-Quota-Remaining") # puede faltar
if left is not None and int(left) < 10_000:
print("Queda poca cuota:", left)
if r.status_code == 200: # con 304 los datos no han cambiado
etag = r.headers.get("ETag")
body = r.json()
pause = body["meta"].get("freshness_sec", pause)
print(body["meta"]["count"], "monedas en la respuesta")
time.sleep(pause)
Cambiar y renovar el plan
- Un plan nuevo se activa justo después del pago: nuevos límites y frescura, la cuota empieza de cero y lo que quedaba del plan anterior se pierde. El sitio te avisa antes de pagar.
- Renovar el mismo plan añade días al plazo y no reinicia la cuota: el periodo de 30 días en curso continúa.
- Tu clave no cambia al cambiar o renovar el plan, así que tus programas no necesitan actualización.
- El descuento por periodo se aplica al precio mensual: Pro por 6 meses cuesta $100 × 0,8 × 6 = $480 en lugar de $600, y por 3 meses, $100 × 0,9 × 3 = $270.
Cómo obtener y guardar la clave se explica en la guía de la clave de Genesis API.
Preguntas y respuestas
¿Qué pasa si la cuota se agota antes de tiempo?
El servidor devuelve 429 rate_limited con Retry-After hasta que la cuota se reinicia, y no se cobra nada. Espera al nuevo periodo o paga un plan superior: se activa al instante, con cuota nueva.
¿Las respuestas 304 y los errores cuentan para los límites?
No para la cuota: solo 200 la consume. Sí cuentan para el límite de peticiones por segundo: las respuestas 304 y los errores ocupan huecos en la ventana por segundo.
¿Cómo compruebo la cuota restante sin gastar una llamada?
Lee X-Quota-Remaining en una respuesta de datos o llama a /account/usage: esa petición no consume llamada. La línea de llamadas usadas de tu perfil también muestra el consumo.
¿Puedo esquivar el límite con varias claves?
No. Cada cuenta recibe una clave, los límites se cuentan por clave y cambiar de dirección IP no los modifica. Abrir varias cuentas para esquivar límites incumple las reglas; si necesitas más, pasa a un plan superior.