Como consultar uma API de criptomoedas sem estourar os limites: ETag, gzip, filtros e novas tentativas após um 429
Em resumo
- Uma API costuma ter três limites: requisições por segundo, uma cota de chamadas por período e o volume de download. Na Genesis API são de 1 a 15 requisições por segundo, de 500 K a 10 M de chamadas a cada 30 dias e 60 MB de dados compactados a cada 10 segundos por chave.
- Defina o intervalo de polling pelo
meta.freshness_sec: consultar mais rápido devolve o mesmo snapshot. OIf-None-Matchtransforma uma repetição em um304gratuito, o gzip e os filtros reduzem o tráfego, e um único dataset completo em vez de uma requisição por moeda economiza chamadas. - Tente de novo
429e503apósRetry-Aftersegundos ou, sem esse cabeçalho, com backoff exponencial mais jitter aleatório. Um token bucket no cliente mantém seu ritmo abaixo do limite, e os cabeçalhosX-RateLimit-*eX-Quota-*mostram a margem restante.
Para consultar uma API sem erros 429, ajuste suas requisições a três limites ao mesmo tempo: requisições por segundo, cota de chamadas do período e volume de dados baixado. Cinco técnicas resolvem: um intervalo não menor que a atualização dos dados, requisições condicionais com ETag, compactação gzip, filtros em vez de downloads enormes e novas tentativas após a pausa que o servidor pede. Os números e o código abaixo são da Genesis API, uma API REST de dados do mercado cripto, mas as técnicas servem para qualquer API HTTP, inclusive as de corretoras.
Três limites de uma API: requisições por segundo, cota e volume
Um rate limit por segundo pega as rajadas: um lote de requisições enviado de uma vez. A cota pega o seu ritmo médio ao longo do período todo, e o limite de volume pega downloads pesados mesmo quando há poucas requisições.
| Limite | O que conta | Genesis API | Ao ultrapassar |
|---|---|---|---|
| Requisições por segundo | Cada requisição, incluindo 304 e erros | 1 no Trial, 2 no Start, 5 no Pro, 15 no Max | 429 rate_limited, Retry-After: 1 |
| Cota por período | Apenas respostas 200 | 500 K, 2 M, 5 M, 10 M de chamadas a cada 30 dias | 429 rate_limited, Retry-After até a cota ser renovada |
| Volume de download | Respostas compactadas de 64 KB ou mais | 60 MB a cada 10 segundos por chave, em todos os planos | 429 download_limited até o fim da janela |
A Genesis API nunca cobra requisições acima de um limite: um 429 não consome cota e não custa nada. Todas as regras estão no guia de limites da Genesis API e na seção Planos e limites da documentação.
As APIs de corretoras podem ser mais complexas. A Binance conta o peso das requisições por endereço IP, e cada endpoint tem o seu próprio peso. Um cliente que continua enviando requisições após um 429 recebe um bloqueio automático de IP com o status 418, e os reincidentes recebem bloqueios mais longos (documentação da Binance).
Intervalo de polling: quantas chamadas você usa em 30 dias
Consultar mais rápido do que os dados são atualizados só traz repetições. O núcleo da Genesis Arbitrage atualiza os dados a cada segundo, enquanto a saída da API para o seu plano é atualizada uma vez a cada meta.freshness_sec segundos: 60 no Trial, 30 no Start, 10 no Pro e 5 no Max. Essa é a atualidade dos dados do seu plano e o piso do seu intervalo de polling. A Genesis API não tem WebSocket nem webhooks, então os dados vêm por polling via REST.
Exemplo ilustrativo: um bot no plano Start — US$ 50 por mês, 2 M de chamadas, 2 requisições por segundo, atualidade de 30 s — consulta quatro endpoints: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread e /market/open-interest.
| Intervalo | Chamadas em 30 dias | Parcela da cota do Start | Repetições de um snapshot |
|---|---|---|---|
| 60 s | 172.800 | 8,64% | nenhuma |
| 30 s | 345.600 | 17,28% | nenhuma |
| 10 s | 1.036.800 | 51,84% | 2 de 3 |
| 5 s | 2.073.600 | 103,68% | 5 de 6 |
Consultar a cada 5 segundos esgota a cota no dia 29: 4 × 86.400 / 5 = 69.120 chamadas por dia, e 2.000.000 / 69.120 ≈ 28,9 dias. Cinco de cada seis respostas repetem um mesmo snapshot com o mesmo meta.updated_at, e sem If-None-Match cada uma custa uma chamada.
Com uma consulta a cada 30 segundos, o ritmo médio é 4 / 30 ≈ 0,13 requisição por segundo. Mas quatro requisições enviadas ao mesmo tempo caem no mesmo segundo, e duas delas recebem um 429. Se você precisa de dados mais frescos que 30 segundos, a resposta é um plano com freshness_sec menor: o Pro atualiza o snapshot a cada 10 segundos, o Max a cada 5.
Requisições condicionais: ETag, If-None-Match e 304
Um ETag é uma etiqueta de versão de uma resposta. O cliente a guarda e a devolve no cabeçalho If-None-Match da próxima requisição à mesma URL; se a versão não mudou, o servidor responde 304 Not Modified. Segundo a RFC 9110, um 304 termina após os cabeçalhos e não tem corpo, então você usa a sua própria cópia dos dados.
Na Genesis API, um 304 não consome cota, mas ainda ocupa uma vaga no limite de requisições por segundo. Só os datasets completos sem filtros recebem etiqueta. As respostas a requisições com coin, exchange, min_spread ou outros filtros, assim como /orderbooks/book e /orderbooks/coin/{coin}, são montadas a cada requisição e vêm sem ETag.
O ETag economiza cota onde os dados mudam menos do que você consulta. A etiqueta dos spreads muda a cada snapshot, então, se você consulta uma vez por freshness_sec, quase toda resposta é um 200.
Exemplo ilustrativo no Pro: as somas diárias da análise de funding, /funding/analytics/daily, são regeneradas a cada hora; depois de acumular um ano de histórico, a seção completa tem cerca de 12 MB em gzip e, sem coin, é entregue no máximo uma vez a cada 300 segundos. Consultar a cada 300 segundos dá 2.592.000 / 300 = 8.640 requisições em 30 dias. Com If-None-Match, a seção é baixada 30 × 24 = 720 vezes, e as outras 8.640 − 720 = 7.920 respostas voltam como 304.
O resultado: 720 chamadas em vez de 8.640, e cerca de 8,6 GB de tráfego em vez de 104 GB. As respostas 304 não contam para o limite de download completo.
Filtros e coin: o que economiza chamadas e o que economiza tráfego
Um filtro reduz a resposta, mas não o número de chamadas: a cota conta respostas, e uma requisição com coin=BTC custa o mesmo que o dataset completo. Então a escolha depende do que acaba primeiro, as chamadas ou o tráfego.
Exemplo ilustrativo no Start: um bot acompanha o funding de cinco moedas. Cinco requisições a /funding/rates com coin a cada 30 segundos somam 5 × 86.400 = 432.000 chamadas em 30 dias, além de cinco requisições por ciclo contra um limite de 2 por segundo. Um /funding/rates completo, com as moedas separadas no código, custa 86.400 chamadas, cinco vezes menos, e recebe um ETag.
| Tarefa | Como pedir | O que economiza |
|---|---|---|
| Várias moedas de um dataset | Dataset completo com If-None-Match, filtro no código | Chamadas: uma requisição em vez de várias |
| Uma moeda de uma seção pesada | O parâmetro coin | Tráfego e o limite de volume |
| Linhas acima de um limiar | min_spread, min_volume | Tráfego, mas cada consulta é uma chamada |
| Uma seção lenta inteira | Dataset completo com If-None-Match | Chamadas e tráfego |
As seções mais pesadas são as da análise de funding: o resumo completo tem cerca de 600 KB em gzip, os pagamentos de 7 dias cerca de 1 MB e as somas diárias até 12 MB (endpoints de funding). Um recorte de uma única moeda com coin fica fora do limite de download completo, que é de uma vez a cada 60 segundos para o resumo e os pagamentos e de uma a cada 300 para as somas diárias.
Compactação gzip
A compactação reduz o número de bytes na rede. O cliente a pede com Accept-Encoding: gzip, e o servidor responde com um corpo compactado e um cabeçalho Content-Encoding: gzip. O requests do Python adiciona gzip ao Accept-Encoding e descompacta a resposta sozinho; o curl faz o mesmo com --compressed.
Na Genesis API, a compactação está ligada a um limite: o volume de download é contado em dados compactados, 60 MB a cada 10 segundos por chave, e as respostas menores que 64 KB não são contadas. Datasets completos e respostas grandes chegam em gzip quando o cliente pede (respostas e erros da Genesis API). Para ver quantos bytes de corpo realmente passaram pela rede, use a variável size_download do curl:
# bytes do corpo na rede com e sem gzip; cada requisição é uma chamada
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "uncompressed: %{size_download}\n" \
-H "X-API-Key: $GENESIS_API_KEY" "$URL"
Tentar de novo após um 429: Retry-After e backoff com jitter
HTTP 429 Too Many Requests é a resposta do servidor a um cliente que ultrapassou um limite. Segundo a RFC 6585, a resposta pode trazer um cabeçalho Retry-After, e segundo a RFC 9110 o seu valor é um número de segundos ou uma data. A Genesis API envia Retry-After com cada 429 e 503, em segundos.
Uma nova tentativa sem pausa quase sempre recebe o mesmo erro e ocupa mais uma vaga na janela por segundo. Se há Retry-After, espere o tempo que o servidor pede. Se não há, espere exponencialmente mais após cada falha: até 1, 2, 4, 8 segundos.
O jitter, um acréscimo aleatório à pausa, importa quando há muitos clientes: sem ele, todos que receberam um erro no mesmo segundo tentam de novo também no mesmo segundo. A função backoff escolhe uma pausa aleatória entre zero e o degrau atual e soma uma fração de segundo ao Retry-After. O fetch repete 429, 500 e 503, e para quando a pausa passa de 10 minutos: é assim que uma cota esgotada aparece.
import os
import random
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session() # reaproveita a conexão TCP, gzip ligado
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # path -> (ETag, data): só datasets completos
def backoff(attempt, retry_after=None, cap=60.0):
"""Pausa antes de uma nova tentativa, em segundos."""
if retry_after and retry_after.isdigit():
return int(retry_after) + random.uniform(0, 1)
return random.uniform(0, min(cap, 2 ** attempt))
def fetch(path, params=None, tries=5):
"""GET na API: devolve (data, cabeçalhos da resposta)."""
for attempt in range(tries):
tag = None if params else cache.get(path, (None,))[0]
try:
r = api.get(BASE + path, params=params, timeout=15,
headers={"If-None-Match": tag} if tag else {})
except (requests.ConnectionError, requests.Timeout):
time.sleep(backoff(attempt))
continue
if r.status_code == 304: # mesmo snapshot, sem gastar cota
return cache[path][1], r.headers
if r.status_code in (429, 500, 503):
wait = backoff(attempt, r.headers.get("Retry-After"))
if wait > 600: # é assim que uma cota esgotada aparece
raise RuntimeError(f"a cota é renovada em {wait:.0f} s")
time.sleep(wait)
continue
r.raise_for_status() # 400, 401, 403, 404, 410: não tentar de novo
data = r.json()["data"]
if not params and "ETag" in r.headers:
cache[path] = (r.headers["ETag"], data)
return data, r.headers
raise RuntimeError(f"{path}: sem resposta após {tries} tentativas")
| Resposta | Pausa | Nova tentativa |
|---|---|---|
429 rate_limited, por segundo | Retry-After: 1 mais uma fração de segundo | Sim |
429 rate_limited, cota | Até a renovação da cota, podem ser dias | Não |
429 download_limited | Retry-After, até o fim da janela | Sim, com requisições mais estreitas |
503 snapshot_not_ready | Retry-After | Sim |
500, timeout, conexão interrompida | Exponencial com jitter | Sim |
400, 401, 403, 404, 410 | — | Não, corrija a requisição |
Você distingue uma cota esgotada do limite por segundo pelo Retry-After: um segundo contra horas ou dias até a renovação, com Monthly call quota exceeded. no corpo da resposta. Os códigos e corpos de erro estão na seção Erros da documentação.
Limitador no cliente: token bucket
Uma nova tentativa lida com um 429; um limitador no cliente o evita. Um token bucket funciona assim: os tokens chegam a rate por segundo, cada requisição pega um, e um balde vazio faz você esperar. A capacidade, burst, define quantas requisições podem sair em sequência sem pausa.
import time
class TokenBucket:
"""No máximo rate requisições por segundo, até burst em sequência."""
def __init__(self, rate, burst=1):
self.rate, self.burst = rate, burst
self.tokens = float(burst)
self.last = time.monotonic()
def take(self):
while True:
now = time.monotonic()
self.tokens = min(self.burst, self.tokens
+ (now - self.last) * self.rate)
self.last = now
if self.tokens >= 1:
self.tokens -= 1
return
time.sleep((1 - self.tokens) / self.rate)
Pegue o limite no campo rps_limit de /account/usage (a seção Uso) ou no cabeçalho X-RateLimit-Limit. Defina o ritmo um pouco abaixo do limite, por exemplo 0.9 * rps_limit: a latência de rede é irregular, então requisições enviadas com meio segundo de diferença podem chegar mais juntas ao servidor.
Monitoramento: os cabeçalhos X-RateLimit-* e X-Quota-*
Uma resposta com dados traz o estado dos seus limites: X-RateLimit-Remaining e X-RateLimit-Reset informam o que resta na janela por segundo e quando ela é renovada, enquanto X-Quota-Remaining, X-Quota-Limit e X-Quota-Reset informam a cota restante, o seu tamanho e o horário unix da renovação. Mais útil que qualquer saldo isolado é o ritmo: que parcela da cota já foi gasta neste ponto do período.
PERIOD = 30 * 86400 # a Genesis API conta a cota por 30 dias
def watch(h):
"""Confere a margem dos limites pelos cabeçalhos da resposta."""
if h.get("X-RateLimit-Remaining") == "0": # janela esgotada
reset = float(h.get("X-RateLimit-Reset", 0))
time.sleep(max(0.0, reset - time.time()))
try:
left = int(h["X-Quota-Remaining"])
limit = int(h["X-Quota-Limit"])
reset = int(h["X-Quota-Reset"])
except (KeyError, ValueError):
return # respostas 429 não trazem cabeçalhos X-Quota-*
used = 1 - left / limit
passed = 1 - (reset - time.time()) / PERIOD
if used > passed + 0.05:
print(f"a cota está adiantada: {used:.0%} usada"
f" com {passed:.0%} do período decorrido")
A função espera a janela ser renovada quando o limite dela se esgota, e avisa quando o uso da cota passa o calendário em mais de 5 pontos percentuais. Exemplo ilustrativo: 70% da cota já foi gasta no dia 15, então, no mesmo ritmo, as chamadas acabam em 15 / 0,7 ≈ 21,4 dias do período. O /account/usage dá os mesmos números sem cabeçalhos: calls_used, calls_limit e period_resets_at.
Um cronograma para vários endpoints
Com vários endpoints, cada um tem o seu próprio intervalo, e as primeiras requisições são espaçadas para não saírem em lote. Escolha o intervalo pela tarefa, mas nunca abaixo de freshness_sec: os spreads precisam do ritmo total do seu plano, enquanto para muitas estratégias um minuto basta para o funding e o open interest.
import heapq
usage, _ = fetch("/account/usage") # não gasta uma chamada
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])
JOBS = { # path -> intervalo de polling, s
"/arbitrage/spot-spot": fresh,
"/funding/spread": max(fresh, 60),
"/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)
while True:
due, path, every = heapq.heappop(queue)
time.sleep(max(0.0, due - time.monotonic()))
bucket.take()
data, hdrs = fetch(path)
watch(hdrs)
print(path, len(data))
heapq.heappush(queue, (due + every, path, every))
No Start, são 86.400 + 43.200 + 43.200 = 172.800 chamadas em 30 dias, 8,64% da cota: spreads a cada 30 segundos, funding e open interest a cada 60. As primeiras requisições saem com 30 / 3 = 10 segundos de diferença, e depois disso cada endpoint mantém o seu próprio ritmo, com o bucket.take() protegendo contra colisões. Um bot construído sobre esse polling, com alertas no Telegram, está em Bot de arbitragem de criptomoedas em Python.
O que fazer diante de um 503 e de erros do servidor
Segundo a RFC 9110, 503 Service Unavailable significa uma sobrecarga temporária ou manutenção, e o servidor pode sugerir uma pausa no Retry-After. Na Genesis API, isso é 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; a pausa costuma ser de poucos segundos.
Enquanto não há resposta nova, o seu bot ainda guarda os dados da última consulta, e esses dados envelhecem. Antes de enviar um sinal, compare meta.updated_at com a hora atual: um par de um snapshot de um minuto atrás pode já ter sumido na corretora. Outros riscos são tratados na lição Riscos da automação.
Repita 500 internal_error, timeouts e conexões interrompidas com backoff exponencial. Se o erro persistir, fale com o suporte informando o valor de X-Request-Id, o horário da requisição em UTC, o endpoint e o código de status. Nunca envie a sua chave.
Perguntas e respostas
Quantas requisições por segundo posso enviar à Genesis API?
Quantas o seu plano permitir: 1 no Trial, 2 no Start, 5 no Pro e 15 no Max. O limite é por chave e inclui respostas 304 e erros. O valor do seu plano está no cabeçalho X-RateLimit-Limit e no campo rps_limit de /account/usage.
Erros e respostas 304 contam na minha cota?
Não. Só uma resposta 200 consome cota; 304, 429, 503 e outros erros são gratuitos e não custam nada. Mesmo assim, eles ocupam vagas no limite de requisições por segundo, então novas tentativas sem pausa provocam novos 429.
Como ficar abaixo de 60 MB a cada 10 segundos?
Ative o gzip: o limite conta dados compactados. Envie If-None-Match com datasets completos: um 304 não tem corpo. Pegue seções pesadas, como a análise de funding, em um recorte por coin, e não baixe o mesmo dataset completo com mais frequência que freshness_sec. Respostas menores que 64 KB não contam e, segundo a documentação, consultar cada dataset na atualidade do seu plano cabe com folga no limite.
O que significa um erro 429 Too Many Requests?
O servidor rejeitou a requisição porque o cliente ultrapassou um limite dentro de uma janela de tempo. A resposta pode trazer Retry-After, o número de segundos de espera; sem ele, dobre a pausa após cada falha. Na Genesis API, um 429 vem com o código rate_limited ou download_limited.