Limites da Genesis API: cota de chamadas, requisições por segundo, atualização dos dados e erros 429
Em resumo
- Seu plano define a cota de chamadas por 30 dias (de 500 mil no Trial a 10 milhões no Max), o limite de requisições por segundo (de 1 a 15) e a atualização dos dados (de 60 a 5 segundos).
- Só uma resposta
200consome cota. Respostas304e erros não custam nada, mas ocupam uma vaga no limite de requisições por segundo; ao passar de um limite, o servidor devolve429e não cobra nada. - Consultar mais rápido que
meta.freshness_secnão traz dados novos: seu plano recebe um snapshot novo uma vez por esse intervalo, eIf-None-Matchtransforma as consultas extras em respostas304gratuitas.
Os limites da Genesis API são quatro tetos por chave: a cota de chamadas para um período de 30 dias, o rate limit em requisições por segundo, a atualização dos dados e o volume de download. Seu plano define os três primeiros; o volume de download é igual para todos: 60 MB de dados compactados a cada 10 segundos. Ao passar de qualquer limite, o servidor devolve um erro 429 e não cobra nada.
Limites por plano
| Plano | Chamadas por 30 dias | Requisições por segundo | Atualização |
|---|---|---|---|
| Trial, $20/mês | 500.000 | 1 | 60 s |
| Start, $50/mês | 2.000.000 | 2 | 30 s |
| Pro, $100/mês | 5.000.000 | 5 | 10 s |
| Max, $200/mês | 10.000.000 | 15 | 5 s |
A atualização dos dados é o intervalo em que seu plano recebe um snapshot novo: a cada 60 segundos no Trial, a cada 5 no Max. As respostas trazem esse valor no campo meta.freshness_sec. Pagar por 3 meses economiza 10%, por 6 meses, 20%. A comparação dos planos está na página de preços da Genesis API, e as regras estão na seção Planos e limites da documentação.
O que consome a cota
Uma chamada é uma resposta 200. Respostas 304 (dados sem alteração) e erros 4xx e 5xx não consomem cota, mas contam para o limite de requisições por segundo. Uma requisição a /account/usage não consome chamada.
A cota vale para um período de 30 dias, não para um mês do calendário. O horário da renovação está no cabeçalho X-Quota-Reset, no campo period_resets_at e na linha «resets …» do seu perfil. Quando a cota acaba, o servidor responde 429 rate_limited, e Retry-After traz o número de segundos até a renovação, que podem ser dias.
Cabeçalhos de rate limit
A resposta de um endpoint de dados traz o estado dos seus limites (valores ilustrativos):
| Cabeçalho | Exemplo | O que mostra |
|---|---|---|
X-RateLimit-Limit | 5 | Limite de requisições por segundo do seu plano |
X-RateLimit-Remaining | 4 | Requisições restantes na janela atual |
X-RateLimit-Reset | 1785200001 | Horário Unix em que a janela é renovada |
X-Quota-Limit | 5000000 | Cota de chamadas do período de 30 dias |
X-Quota-Remaining | 4815799 | Chamadas restantes no período |
X-Quota-Reset | 1786492800 | Horário Unix em que a cota é renovada |
Retry-After | 1 | Segundos de espera antes de tentar de novo, em 429 e 503 |
A janela de requisições por segundo dura um segundo; por isso, numa resposta normal, X-RateLimit-Reset aponta para o início do segundo seguinte. A cota restante do exemplo: 5.000.000 − 184.201 = 4.815.799 chamadas, os mesmos números que /account/usage devolve.
O 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 | Plano: trial, start, pro ou max |
calls_used | int | Chamadas usadas no período atual |
calls_limit | int | Cota de chamadas por período |
rps_limit | int | Limite de requisições por segundo |
freshness_sec | int | Atraso dos dados, em segundos |
period_resets_at | int | Horário Unix em que a cota é renovada |
O endpoint está disponível em todos os planos e é descrito na seção Uso. Chame-o ao iniciar um bot, para conferir o plano e a cota restante antes de começar a consultar.
Erros 429: rate_limited e download_limited
| Resposta | Quando aparece | O que fazer |
|---|---|---|
429 rate_limited | Mais requisições por segundo do que o plano permite | Esperar o tempo de Retry-After e espaçar as requisições |
429 rate_limited | A cota do período acabou | Esperar a renovação ou trocar de plano |
429 rate_limited | Download completo da análise de funding antes do permitido | Pedir um recorte com coin ou enviar If-None-Match |
429 download_limited | Mais de 60 MB de dados compactados em 10 segundos | Esperar o tempo de Retry-After e restringir a requisição com filtros |
O código de status 429 Too Many Requests é definido na RFC 6585, onde Retry-After é opcional. A Genesis API o envia com todo 429, sempre em segundos.
Respostas abaixo de 64 KB não contam para o volume de download, e consultar todos os conjuntos de dados na atualização do seu plano cabe no limite com folga. Downloads completos da análise de funding sem coin têm limite próprio: /funding/analytics/summary e /funding/analytics/recent uma vez a cada 60 segundos, /funding/analytics/daily uma vez a cada 300 segundos por chave. Requisições com coin e respostas 304 não têm limite; os detalhes estão na seção Análise de funding.
Acesso por plano e 403 plan_restricted
| Plano | O que está liberado |
|---|---|
| Trial | Arbitragem CEX (Spot – Spot, Spot – Futuros, Futuros – Futuros), taxas de financiamento (funding) e spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, sinais de IA, busca de moedas, /account/usage |
| Start | Tudo do Trial, mais ações /arbitrage/stocks, seções on-chain /onchain/{section}, arbitragem de mercados de previsão nos modos exact e dutch, status das plataformas |
| Pro e Max | Todos os endpoints: DEX – Spot, DEX – Futuros, Crosschain, DEX Dumps, livros de ofertas, análise de funding, análise de mercados de previsão, smart money, negociações, traders, os modos llm e sport, swaps DEX, análise OnChain e moeda |
Um endpoint fora do seu plano devolve 403, assim como uma requisição mode=sport a /predictions/arbitrage no Start:
{
"success": false,
"error": {
"code": "plan_restricted",
"message": "This endpoint is not included in your plan."
}
}
Um 403 não consome cota. Tentar de novo não adianta: só um plano superior libera o acesso.
Como dimensionar o plano para a sua carga
Exemplo ilustrativo: um bot consulta três endpoints, /arbitrage/spot-spot, /funding/spread e /market/open-interest, a cada 10 segundos, 24 horas por dia.
- Requisições por segundo: 3 / 10 = 0,3 em média. Se as três saem ao mesmo tempo, caem no mesmo segundo, e Trial e Start devolvem
429para as excedentes. - Chamadas por dia: 86.400 / 10 = 8.640 consultas, 8.640 × 3 = 25.920 chamadas.
- Chamadas por 30 dias: 25.920 × 30 = 777.600. É mais que a cota do Trial, de 500.000; no Start são 777.600 / 2.000.000 = 38,88% da cota.
- Atualização: no Start o snapshot é atualizado a cada 30 segundos, ou seja, 86.400 / 30 = 2.880 vezes por dia. Os dados novos vêm de 2.880 × 3 × 30 = 259.200 chamadas, e as outras 777.600 − 259.200 = 518.400 devolvem o mesmo conteúdo.
O mesmo bot consultando na atualização de cada plano:
| Atualização e consulta | Chamadas por 30 dias | Plano | Fração da cota |
|---|---|---|---|
| A cada 60 s | 129.600 | Trial | 26% |
| A cada 30 s | 259.200 | Start | 13% |
| A cada 10 s | 777.600 | Pro | 16% |
| A cada 5 s | 1.555.200 | Max | 16% |
Consultar a cada 10 segundos faz sentido a partir do Pro: 777.600 / 5.000.000 = 15,552% da cota, e o limite de 5 requisições por segundo comporta o envio das três de uma vez. Se o bot aceita dados com 30 segundos de idade, o Start com consulta a cada 30 segundos custa 259.200 / 2.000.000 = 12,96% da cota.
Consultar sem chamadas desperdiçadas: ETag e Retry-After
Seu plano recebe um snapshot novo a cada meta.freshness_sec segundos, e consultar mais rápido devolve o mesmo snapshot com o mesmo meta.updated_at. Sem o cabeçalho If-None-Match, essa resposta é um 200 e uma chamada gasta. Com ele, o servidor responde 304 sem corpo: a cota fica intacta, mas uma vaga do limite por segundo é ocupada.
Um ETag não vem em toda resposta. Conjuntos de dados completos o devolvem, isto é, requisições sem filtros, como /funding/spread no exemplo abaixo. Uma resposta filtrada (coin, min_spread e outros) não tem ETag, e cada consulta custa uma chamada: filtros economizam tráfego, o ETag economiza cota. Novas tentativas e compressão são tratadas em como consultar uma API com eficiência e no guia de respostas e erros.
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: # a cota acabou, paramos aqui
raise SystemExit(f"Cota esgotada, renova em {wait} s")
time.sleep(wait)
continue
r.raise_for_status() # tentar de novo não resolve 401 nem 403
left = r.headers.get("X-Quota-Remaining") # pode estar ausente
if left is not None and int(left) < 10_000:
print("Cota acabando:", left)
if r.status_code == 200: # com 304 os dados não mudaram
etag = r.headers.get("ETag")
body = r.json()
pause = body["meta"].get("freshness_sec", pause)
print(body["meta"]["count"], "moedas na resposta")
time.sleep(pause)
Trocar e renovar o plano
- Um plano novo vale logo após o pagamento: novos limites e atualização, a cota começa do zero e o que restava do plano anterior é perdido. O site avisa antes do pagamento.
- Renovar o mesmo plano acrescenta dias ao prazo e não zera a cota: o período de 30 dias em andamento continua.
- Sua chave continua a mesma ao trocar ou renovar o plano, então seus programas não precisam de atualização.
- O desconto por período vale sobre o preço mensal: Pro por 6 meses custa $100 × 0,8 × 6 = $480 em vez de $600, e por 3 meses, $100 × 0,9 × 3 = $270.
Como obter e guardar a chave está no guia da chave da Genesis API.
Perguntas e respostas
O que acontece se a cota acabar antes da hora?
O servidor devolve 429 rate_limited com Retry-After até a cota ser renovada, e nada é cobrado. Espere o novo período ou pague um plano superior: ele vale na hora, com cota nova.
Respostas 304 e erros contam para os limites?
Não para a cota: só 200 a consome. Elas contam para o limite de requisições por segundo: respostas 304 e erros ocupam vagas na janela por segundo.
Como verificar a cota restante sem gastar uma chamada?
Leia X-Quota-Remaining numa resposta de dados ou chame /account/usage: essa requisição não consome chamada. A linha de chamadas usadas no seu perfil também mostra o consumo.
Posso contornar o limite com várias chaves?
Não. Cada conta recebe uma chave, os limites são contados por chave e trocar de endereço IP não os altera. Abrir várias contas para contornar limites viola as regras; se precisar de mais, mude para um plano superior.