Respuestas y errores de Genesis API: formato JSON, ETag y 304, códigos HTTP
En resumen
- Una respuesta correcta de Genesis API es un sobre con
success,dataymeta; un error essuccess: falsemás un objetoerrorcon código y mensaje. - Si envías el ETag anterior en
If-None-Match, el servidor devuelve304sin cuerpo cuando los datos no han cambiado, y un 304 no consume cuota. - Reintenta
429y503tras la pausa deRetry-After. Reintentar no arregla400,401,403,404ni410: cambia la petición, la clave o el plan.
Genesis API responde cada petición en JSON, un formato de datos de texto formado por objetos clave–valor y arrays. Una respuesta correcta siempre llega en el mismo sobre con success, data y meta; un error llega con un código de estado HTTP y un objeto error. El código de estado le dice a tu programa qué hacer: usar los datos, esperar Retry-After segundos y reintentar, o corregir la petición.
Sobre de la respuesta: success, data y meta
Una respuesta abreviada de GET /arbitrage/spot-spot tomada de la documentación (el endpoint está disponible en todos los planes):
{
"success": true,
"data": [
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"spread_pct": 0.11,
…
}
],
"meta": {
"count": 214,
"updated_at": 1783802410,
"freshness_sec": 10,
"plan": "pro"
}
}
| Campo | Tipo | Contenido |
|---|---|---|
success | boolean | true: la petición se ejecutó; false: error |
data | array u objeto | Los datos del endpoint |
meta.count | int | Número de elementos en data |
meta.updated_at | int | Hora unix en que se construyeron los datos |
meta.freshness_sec | int | Retraso de entrega de tu plan, en segundos |
meta.plan | string | Tu plan, pro en el ejemplo |
La excepción es la analítica de funding: su meta contiene count, updated_at y schema_version, sin freshness_sec ni plan. El sobre se describe en la sección Formato de respuesta de la documentación, y los campos de data en la página de cada endpoint.
Tres convenciones valen para todos los endpoints:
- un valor vacío es
null: por ejemplo,max_position_usden DEX – Futuros esnullcuando la exchange no informa un límite de posición; - los spreads y las tasas son porcentajes:
"spread_pct": 0.92significa 0,92 %, no 92 %; - las marcas de tiempo son segundos unix:
1783802410es el 11 de julio de 2026, 20:40:10 UTC; las fechas enviadas como cadena, comopool_created_aten Cross-chain, tienen tipo string en la documentación.
data: un array de filas o un objeto
La forma de data se indica en la descripción de cada endpoint. En GET /arbitrage/spot-spot es un array: un elemento por par de arbitraje, como una fila de la tabla del sitio. En GET /account/usage es un único objeto con el estado de tu clave:
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": { … }
}
/account/usage está disponible en todos los planes y muestra tu plan, el consumo de cuota y freshness_sec: consultar con más frecuencia no aporta nada. Los campos se describen en Uso, y la primera petición se recorre paso a paso en el inicio rápido. El código que trabaja con varios endpoints debe comprobar la forma de forma explícita: isinstance(data, list) en Python.
Filtros: opcionales, sin ellos llega el conjunto completo
Todos los parámetros de filtro son opcionales: una petición sin ellos devuelve el conjunto de datos completo del endpoint. Indica varias exchanges en exchange separadas por comas, y una moneda por su ticker en coin:
curl -G --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
La opción -G convierte los parámetros -d en una cadena de consulta: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Escribe los nombres de las exchanges tal como vuelven en los campos de la respuesta: ByBit, Gate, MEXC. Los parámetros de los endpoints de arbitraje están en la guía de endpoints de arbitraje.
La cuota cuenta respuestas, no filas: una petición con filtros o sin ellos es una llamada. Un filtro reduce el cuerpo de la respuesta y, con él, el tráfico y el consumo del límite de descarga. Todos los límites se explican en la guía de límites de Genesis API.
Compresión gzip
Genesis API envía los conjuntos completos y las respuestas grandes comprimidos con gzip cuando el cliente manda la cabecera Accept-Encoding: gzip (RFC 9110, sección 12.5.3). Una respuesta pequeña puede llegar sin comprimir.
requests de Python envía esa cabecera por sí mismo y descomprime la respuesta. curl no pide compresión sin la opción --compressed; con ella, la pide y descomprime.
El límite de descarga cuenta los datos comprimidos: como máximo 60 MB cada 10 segundos por clave, y las respuestas de menos de 64 KB no se cuentan. Al superar el límite recibes 429 download_limited.
ETag y 304: omite los datos sin cambios
ETag es una cabecera de respuesta con una etiqueta de versión de los datos. El cliente devuelve esa etiqueta en la cabecera If-None-Match. Si los datos no han cambiado, el servidor responde 304 Not Modified sin cuerpo; si han cambiado, un 200 normal con datos nuevos y un ETag nuevo.
# Conjunto completo, sin filtros: mostrar solo las cabeceras de la respuesta
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# Repetir con el ETag de la primera respuesta (valor ilustrativo)
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-H 'If-None-Match: W/"5d1f0c9a"'
Un ETag llega con la respuesta a una petición sin filtros y cambia con cada nueva instantánea de datos. La respuesta a una petición con filtros se construye para esa petición y llega sin ETag; ahí el propio filtro ahorra tráfico. Los ETag ayudan más con datos de cambio lento: el resumen de la analítica de funding cambia su ETag más o menos cada 15 minutos, y las respuestas 304 no cuentan para su límite de descarga completa.
Una respuesta 304 no consume cuota, pero sí cuenta para el límite de peticiones por segundo. Devuelve la etiqueta exactamente como llegó: según la RFC 9110 es una cadena entre comillas, y el prefijo W/ marca una etiqueta débil.
Códigos de error y qué hacer
Ante un error, Genesis API devuelve el estado HTTP correspondiente y un cuerpo con success: false:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code es un código legible por máquina sobre el que tu programa puede ramificar. error.message es la explicación para una persona: en 400 da el motivo, en 410 la dirección de reemplazo.
| HTTP | error.code | Significado | Qué hacer |
|---|---|---|---|
400 | bad_request | Parámetros de la petición no válidos, por ejemplo volume=700 en /orderbooks/exec | Corrige los parámetros según message: la misma petición volverá a fallar |
401 | invalid_key | Clave ausente, inválida o revocada, o la suscripción a la API ha caducado | Revisa la cabecera X-API-Key y el estado de la suscripción en tu perfil |
403 | plan_restricted | El endpoint no está en tu plan | Pasa a un plan que lo incluya o elimina la petición |
404 | not_found | Endpoint o recurso no encontrado: conjunto de datos, sección, moneda, libro de órdenes | Comprueba la ruta y los parámetros con la documentación |
410 | gone | El endpoint está retirado | Cambia a la dirección indicada en message |
429 | rate_limited | Se superó el límite de peticiones por segundo o se agotó la cuota del periodo | Espera Retry-After segundos y reduce el ritmo; si la cuota se agotó, espera al reinicio o sube de plan |
429 | download_limited | Se superó el volumen de descarga: 60 MB de datos comprimidos cada 10 s por clave | Espera Retry-After, reduce el tráfico con filtros, coin e If-None-Match |
500 | internal_error | Error interno | Reintenta más tarde; si persiste, escribe a soporte con el X-Request-Id |
503 | snapshot_not_ready | Los datos se están reconstruyendo o su fuente se está reiniciando | Reintenta pasados Retry-After segundos |
La cabecera Retry-After llega con 429 y 503 y contiene los segundos de espera: normalmente unos pocos, pero cuando se agota la cuota del periodo es el tiempo hasta el reinicio de la cuota, que pueden ser días. Los errores 4xx y 5xx no consumen cuota, pero sí cuentan para el límite de peticiones por segundo, así que un reintento temprano casi seguro devolverá el mismo error. Términos del glosario: HTTP 429 y rate limit.
X-Request-Id: qué enviar a soporte
Cada respuesta de Genesis API, correcta o no, lleva una cabecera X-Request-Id con el identificador de la petición. Si un error se repite o los datos parecen incorrectos, envía a soporte:
- el valor de
X-Request-Id; - la hora de la petición en UTC;
- el endpoint con sus parámetros, por ejemplo
GET /arbitrage/spot-spot?coin=BTC; - el estado HTTP y
error.code.
No envíes tu clave. Si acabó en un chat, en registros o en código que otras personas pueden ver, reemítela en tu perfil: la clave anterior deja de funcionar al instante.
Orden para procesar una respuesta
Comprueba el código de estado
200: leedataymeta, y guarda el ETag si llegó.304: usa los datos de la respuesta anterior.Gestiona los errores temporales
429y503con una pausa corta: esperaRetry-Aftersegundos y reintenta, como máximo tres veces seguidas.500: reintenta más tarde.Detente ante errores de petición
400,401,403,404,410y un429con una pausa de horas o días: corrige los parámetros, la clave o el plan, o espera al reinicio de la cuota.Comprueba la antigüedad de los datos
Compara
meta.updated_atcon la hora actual: un bot que actúa sobre una instantánea antigua ve spreads que ya no existen.Programa la siguiente petición
No antes de
meta.freshness_secsegundos después, conIf-None-Matchen las peticiones sin filtros.
Una función get_json en Python
La función reúne estas reglas: guarda el último ETag de cada dirección y devuelve los datos anteriores ante un 304, espera Retry-After en 429 y 503 y reintenta hasta tres veces, pero no espera pausas de más de un minuto. Los demás errores lanzan una excepción con el estado, el mensaje y el X-Request-Id. La clave se toma de la variable de entorno GENESIS_API_KEY.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # (ruta, parámetros) -> (ETag, datos)
class GenesisError(Exception):
def __init__(self, status, text):
super().__init__(f"{status} {text}")
self.status = status
def get_json(path, params=None):
key = (path, tuple(sorted((params or {}).items())))
for attempt in range(4): # una petición más hasta 3 reintentos
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = session.get(BASE + path, params=params,
headers=hdr, timeout=15)
if r.status_code == 304:
return cache[key][1] # los datos no han cambiado
wait = float(r.headers.get("Retry-After", 1))
if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
time.sleep(wait) # nunca esperar horas ni días
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "no es JSON") from None
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise GenesisError(r.status_code, (
f"{err.get('code')}: {err.get('message')}; "
f"X-Request-Id {r.headers.get('X-Request-Id')}"))
if "ETag" in r.headers: # solo en respuestas sin filtros
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
El parámetro timeout=15 es imprescindible: sin tiempo de espera máximo, requests aguarda una respuesta para siempre.
Consulta al intervalo de tu plan: el conjunto completo llega con un ETag y las filas se filtran en el código. Los errores 4xx detienen el programa; un fallo del servidor espera al siguiente ciclo.
pause = get_json("/account/usage")["freshness_sec"]
while True:
try:
rows = get_json("/arbitrage/spot-spot") # conjunto completo
top = [x for x in rows if x["spread_pct"] >= 1]
print(len(top), "pares con un spread del 1 % o más")
except GenesisError as e:
if e.status < 500:
raise # 4xx: la petición, la clave, el plan o la cuota
print("error del servidor, se reintenta en el siguiente ciclo:", e)
time.sleep(pause)
Preguntas y respuestas
¿Una respuesta 304 consume cuota?
No. Solo las respuestas 200 consumen cuota. Las respuestas 304 y los errores 4xx y 5xx son gratuitos, pero cuentan para el límite de peticiones por segundo.
¿Qué hago tras un 410 ?
El endpoint está retirado y la dirección de reemplazo figura en error.message. Por ejemplo, GET /arbitrage/predictions se retiró el 15 de noviembre de 2026 y su message apunta a /predictions/arbitrage. Actualiza la ruta en tu código.
¿Por qué data está vacío si no hay error?
Los filtros eliminaron todas las filas: por ejemplo, min_spread es mayor que todos los spreads actuales. Una respuesta así tiene meta.count igual a 0; relaja el filtro.
¿Por qué no hay ETag en la respuesta?
Un ETag llega con la respuesta a una petición sin filtros. La respuesta a una petición con coin, exchange, min_spread u otro filtro se construye para esa petición y llega sin etiqueta, así que If-None-Match no se aplica.