Genesis Arbitrage

Genesis Arbitrage · · 12 min de lectura

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, data y meta; un error es success: false más un objeto error con código y mensaje.
  • Si envías el ETag anterior en If-None-Match, el servidor devuelve 304 sin cuerpo cuando los datos no han cambiado, y un 304 no consume cuota.
  • Reintenta 429 y 503 tras la pausa de Retry-After. Reintentar no arregla 400, 401, 403, 404 ni 410: 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"
  }
}
CampoTipoContenido
successbooleantrue: la petición se ejecutó; false: error
dataarray u objetoLos datos del endpoint
meta.countintNúmero de elementos en data
meta.updated_atintHora unix en que se construyeron los datos
meta.freshness_secintRetraso de entrega de tu plan, en segundos
meta.planstringTu 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:

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.

HTTPerror.codeSignificadoQué hacer
400bad_requestParámetros de la petición no válidos, por ejemplo volume=700 en /orderbooks/execCorrige los parámetros según message: la misma petición volverá a fallar
401invalid_keyClave ausente, inválida o revocada, o la suscripción a la API ha caducadoRevisa la cabecera X-API-Key y el estado de la suscripción en tu perfil
403plan_restrictedEl endpoint no está en tu planPasa a un plan que lo incluya o elimina la petición
404not_foundEndpoint o recurso no encontrado: conjunto de datos, sección, moneda, libro de órdenesComprueba la ruta y los parámetros con la documentación
410goneEl endpoint está retiradoCambia a la dirección indicada en message
429rate_limitedSe superó el límite de peticiones por segundo o se agotó la cuota del periodoEspera Retry-After segundos y reduce el ritmo; si la cuota se agotó, espera al reinicio o sube de plan
429download_limitedSe superó el volumen de descarga: 60 MB de datos comprimidos cada 10 s por claveEspera Retry-After, reduce el tráfico con filtros, coin e If-None-Match
500internal_errorError internoReintenta más tarde; si persiste, escribe a soporte con el X-Request-Id
503snapshot_not_readyLos datos se están reconstruyendo o su fuente se está reiniciandoReintenta 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:

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

  1. Comprueba el código de estado

    200: lee data y meta, y guarda el ETag si llegó. 304: usa los datos de la respuesta anterior.

  2. Gestiona los errores temporales

    429 y 503 con una pausa corta: espera Retry-After segundos y reintenta, como máximo tres veces seguidas. 500: reintenta más tarde.

  3. Detente ante errores de petición

    400, 401, 403, 404, 410 y un 429 con una pausa de horas o días: corrige los parámetros, la clave o el plan, o espera al reinicio de la cuota.

  4. Comprueba la antigüedad de los datos

    Compara meta.updated_at con la hora actual: un bot que actúa sobre una instantánea antigua ve spreads que ya no existen.

  5. Programa la siguiente petición

    No antes de meta.freshness_sec segundos después, con If-None-Match en 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.