Respostas e erros da Genesis API: formato JSON, ETag e 304, códigos HTTP
Em resumo
- Uma resposta bem-sucedida da Genesis API é um envelope com
success,dataemeta; um erro ésuccess: falsemais um objetoerrorcom código e mensagem. - Se você enviar o ETag anterior em
If-None-Match, o servidor devolve304sem corpo quando os dados não mudaram, e um 304 não gasta cota. - Repita
429e503após a pausa deRetry-After. Repetir não corrige400,401,403,404nem410: mude a requisição, a chave ou o plano.
A Genesis API responde a cada requisição em JSON, um formato de dados em texto formado por objetos chave–valor e arrays. Uma resposta bem-sucedida sempre vem no mesmo envelope com success, data e meta; um erro vem com um código de status HTTP e um objeto error. O código de status diz ao seu programa o que fazer: usar os dados, esperar Retry-After segundos e tentar de novo, ou corrigir a requisição.
Envelope da resposta: success, data e meta
Uma resposta resumida de GET /arbitrage/spot-spot, tirada da documentação (o endpoint está disponível em todos os planos):
{
"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 | Conteúdo |
|---|---|---|
success | boolean | true: a requisição deu certo, false: erro |
data | array ou objeto | Os dados do endpoint |
meta.count | int | Número de itens em data |
meta.updated_at | int | Hora unix em que os dados foram montados |
meta.freshness_sec | int | Atraso de entrega do seu plano, em segundos |
meta.plan | string | Seu plano, pro no exemplo |
A exceção é a análise de funding: o meta dela traz count, updated_at e schema_version, sem freshness_sec nem plan. O envelope está descrito na seção Formato de resposta da documentação, e os campos de data na página de cada endpoint.
Três convenções valem para todos os endpoints:
- um valor vazio é
null: por exemplo,max_position_usdem DEX – Futuros énullquando a exchange não informa limite de posição; - spreads e taxas são percentuais:
"spread_pct": 0.92significa 0,92%, não 92%; - os carimbos de data e hora são em segundos unix:
1783802410é 11 de julho de 2026, 20:40:10 UTC; datas enviadas como texto, comopool_created_atem Cross-chain, têm o tipo string na documentação.
data: um array de linhas ou um objeto
O formato de data é indicado na descrição de cada endpoint. Em GET /arbitrage/spot-spot é um array: um item por par de arbitragem, como uma linha da tabela do site. Em GET /account/usage é um único objeto com o estado da sua chave:
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á disponível em todos os planos e mostra seu plano, o uso da cota e freshness_sec: consultar com mais frequência não traz nada. Os campos estão descritos em Uso, e a primeira requisição é percorrida passo a passo no início rápido. Código que trabalha com vários endpoints deve verificar o formato de forma explícita: isinstance(data, list) em Python.
Filtros: opcionais, sem eles vem o conjunto completo
Todos os parâmetros de filtro são opcionais: uma requisição sem eles devolve o conjunto de dados completo do endpoint. Liste várias exchanges em exchange separadas por vírgula e indique uma moeda pelo ticker em 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"
A opção -G transforma os parâmetros -d em uma query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Escreva os nomes das exchanges como voltam nos campos da resposta: ByBit, Gate, MEXC. Os parâmetros dos endpoints de arbitragem estão no guia de endpoints de arbitragem.
A cota conta respostas, não linhas: uma requisição com ou sem filtros é uma chamada. Um filtro reduz o corpo da resposta e, com ele, o tráfego e o uso do limite de download. Todos os limites estão no guia de limites da Genesis API.
Compressão gzip
A Genesis API envia conjuntos completos e respostas grandes compactados em gzip quando o cliente manda o cabeçalho Accept-Encoding: gzip (RFC 9110, seção 12.5.3). Uma resposta pequena pode chegar sem compressão.
O requests do Python envia esse cabeçalho sozinho e descompacta a resposta. O curl não pede compressão sem a opção --compressed; com ela, ele pede e descompacta.
O limite de download conta os dados compactados: no máximo 60 MB a cada 10 segundos por chave, e respostas com menos de 64 KB não são contadas. Acima do limite, você recebe 429 download_limited.
ETag e 304: pule dados que não mudaram
ETag é um cabeçalho de resposta com uma etiqueta de versão dos dados. O cliente devolve essa etiqueta no cabeçalho If-None-Match. Se os dados não mudaram, o servidor responde 304 Not Modified sem corpo; se mudaram, um 200 comum com dados novos e um novo ETag.
# Conjunto completo, sem filtros: mostrar apenas os cabeçalhos da resposta
curl -sS -D - -o /dev/null --compressed \
"https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
# Repetir com o ETag da primeira resposta (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"'
Um ETag vem com a resposta a uma requisição sem filtros e muda a cada novo instantâneo dos dados. A resposta a uma requisição filtrada é montada para ela e vem sem ETag; nesse caso, o próprio filtro economiza tráfego. Os ETags ajudam mais em dados de mudança lenta: o resumo da análise de funding troca de ETag mais ou menos a cada 15 minutos, e as respostas 304 não contam para o limite de download completo dele.
Uma resposta 304 não gasta cota, mas conta para o limite de requisições por segundo. Devolva a etiqueta exatamente como chegou: segundo a RFC 9110, é uma string entre aspas, e o prefixo W/ marca uma etiqueta fraca.
Códigos de erro e o que fazer
Em caso de erro, a Genesis API devolve o status HTTP correspondente e um corpo com success: false:
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Requests per second limit exceeded."
}
}
error.code é um código legível por máquina, no qual seu programa pode se basear para ramificar a lógica. error.message é a explicação para uma pessoa: no 400 traz o motivo, no 410 o endereço substituto.
| HTTP | error.code | Significado | O que fazer |
|---|---|---|---|
400 | bad_request | Parâmetros da requisição inválidos, por exemplo volume=700 em /orderbooks/exec | Corrija os parâmetros conforme message: a mesma requisição falhará de novo |
401 | invalid_key | Chave ausente, inválida ou revogada, ou assinatura da API expirada | Verifique o cabeçalho X-API-Key e o status da assinatura no seu perfil |
403 | plan_restricted | O endpoint não faz parte do seu plano | Mude para um plano que o inclua ou remova a requisição |
404 | not_found | Endpoint ou recurso não encontrado: conjunto de dados, seção, moeda, livro de ofertas | Confira o caminho e os parâmetros na documentação |
410 | gone | O endpoint foi desativado | Passe para o endereço indicado em message |
429 | rate_limited | Limite de requisições por segundo excedido ou cota do período esgotada | Espere Retry-After segundos e reduza o ritmo; se a cota esgotou, aguarde a renovação ou troque de plano |
429 | download_limited | Volume de download excedido: 60 MB de dados compactados a cada 10 s por chave | Espere Retry-After, reduza o tráfego com filtros, coin e If-None-Match |
500 | internal_error | Erro interno | Tente de novo mais tarde; se persistir, fale com o suporte informando o X-Request-Id |
503 | snapshot_not_ready | Os dados estão sendo reconstruídos ou a fonte deles está reiniciando | Tente de novo após Retry-After segundos |
O cabeçalho Retry-After vem com 429 e 503 e traz o número de segundos de espera: em geral poucos segundos, mas, quando a cota do período esgota, é o tempo até a renovação da cota, que pode ser de dias. Erros 4xx e 5xx não gastam cota, mas contam para o limite de requisições por segundo, então uma nova tentativa antecipada provavelmente devolverá o mesmo erro. Termos do glossário: HTTP 429 e rate limit.
X-Request-Id: o que enviar ao suporte
Toda resposta da Genesis API, com sucesso ou não, traz um cabeçalho X-Request-Id com o identificador da requisição. Se um erro se repete ou os dados parecem errados, envie ao suporte:
- o valor de
X-Request-Id; - a hora da requisição em UTC;
- o endpoint com seus parâmetros, por exemplo
GET /arbitrage/spot-spot?coin=BTC; - o status HTTP e
error.code.
Não envie sua chave. Se ela foi parar em um chat, em logs ou em código que outras pessoas podem ver, gere-a de novo no seu perfil: a chave antiga deixa de funcionar imediatamente.
Ordem de tratamento da resposta
Verifique o código de status
200: leiadataemetae guarde o ETag, se veio.304: use os dados da resposta anterior.Trate os erros temporários
429e503com pausa curta: espereRetry-Aftersegundos e tente de novo, no máximo três vezes seguidas.500: tente mais tarde.Pare nos erros de requisição
400,401,403,404,410e um429com pausa de horas ou dias: corrija os parâmetros, a chave ou o plano, ou aguarde a renovação da cota.Verifique a idade dos dados
Compare
meta.updated_atcom a hora atual: um bot que age sobre um instantâneo antigo vê spreads que já sumiram.Agende a próxima requisição
Não antes de
meta.freshness_secsegundos depois, comIf-None-Matchnas requisições sem filtros.
Uma função get_json em Python
A função reúne essas regras: guarda o último ETag de cada endereço e devolve os dados anteriores num 304, espera Retry-After em 429 e 503 e tenta de novo até três vezes, mas não espera pausas maiores que um minuto. Os demais erros lançam uma exceção com o status, a mensagem e o X-Request-Id. A chave vem da variável de ambiente 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 = {} # (caminho, parâmetros) -> (ETag, dados)
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): # uma requisição mais até 3 novas tentativas
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] # os dados não mudaram
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 ou dias
continue
try:
body = r.json()
except ValueError:
raise GenesisError(r.status_code, "não é 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: # só em respostas sem filtros
cache[key] = (r.headers["ETag"], body["data"])
return body["data"]
O parâmetro timeout=15 é obrigatório: sem tempo limite, o requests espera uma resposta para sempre.
Consulta no intervalo do seu plano: o conjunto completo vem com ETag e as linhas são filtradas no código. Erros 4xx interrompem o programa; uma falha do servidor espera o próximo 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 com spread de 1% ou mais")
except GenesisError as e:
if e.status < 500:
raise # 4xx: a requisição, a chave, o plano ou a cota
print("erro do servidor, nova tentativa no próximo ciclo:", e)
time.sleep(pause)
Perguntas e respostas
Uma resposta 304 gasta cota?
Não. Só as respostas 200 gastam cota. As respostas 304 e os erros 4xx e 5xx são gratuitos, mas contam para o limite de requisições por segundo.
O que fazer após um 410 ?
O endpoint foi desativado e o endereço substituto está em error.message. Por exemplo, GET /arbitrage/predictions foi desativado em 15 de novembro de 2026 e o message dele aponta para /predictions/arbitrage. Atualize o caminho no seu código.
Por que data está vazio sem erro?
Os filtros removeram todas as linhas: por exemplo, min_spread está acima de todos os spreads atuais. Uma resposta assim tem meta.count igual a 0; afrouxe o filtro.
Por que não há ETag na resposta?
Um ETag vem com a resposta a uma requisição sem filtros. A resposta a uma requisição com coin, exchange, min_spread ou outro filtro é montada para ela e vem sem etiqueta, então If-None-Match não se aplica.