Erros e limites de API: 429, backoff e o que fazer
Guia prático dos erros de uma API de dados: o que significa cada status HTTP, como tratar o 429 com Retry-After e backoff, e o código que resolve isso.
Publicado em 30 de outubro de 2026 · 7 min de leitura
A diferença entre um bot que roda meses sozinho e um que cai toda semana quase nunca está no código bonito: está no tratamento de erro. Uma API de dados ao vivo vai te devolver 429 em algum momento, a sua internet vai oscilar, e o servidor do outro lado vai reiniciar. Este guia mostra o que cada erro significa, o que fazer com ele e, no fim, um cliente em Python que trata todos de uma vez.
Os exemplos usam a API da LynxMetrics, mas os códigos HTTP e os padrões valem para qualquer API REST. Se "status HTTP" e "cabeçalho" ainda são novidade, comece pelo guia o que é uma API e como se conectar a uma.
Os dois tipos de erro
Separe desde o começo, porque o tratamento é oposto:
- Erro seu, que não melhora sozinho (400, 401, 403, 404): repetir o mesmo pedido devolve o mesmo erro. O programa deve parar e avisar, não insistir.
- Erro temporário (429, 500, 502, 504, falha de rede): o mesmo pedido pode funcionar daqui a alguns segundos. Aqui sim vale esperar e tentar de novo.
Um laço que repete um 401 mil vezes por minuto é o jeito mais rápido de queimar o seu limite sem receber um dado.
Os códigos, um por um
| Status | Código | O que aconteceu | O que fazer |
|---|---|---|---|
| 400 | bad_request | Um parâmetro com formato inválido, como um before ou after que não é data ISO 8601 nem id de rodada | Corrigir a chamada |
| 401 | unauthorized | A chave não foi enviada, está errada ou foi revogada | Conferir o cabeçalho x-api-key e copiar a chave de novo no painel |
| 403 | key_wrong_api | A chave é de outra API do catálogo | Usar a chave da API certa; cada chave abre uma só |
| 403 | trial_expired | O prazo do teste grátis acabou | Assinar o projeto ou abrir um teste novo depois de 24 horas |
| 403 | subscription_required | O projeto não tem assinatura ativa | Reativar no painel |
| 402 | payment_pending | O pagamento não entrou (cartão recusado, Pix vencido) | Pagar; as chaves voltam sozinhas em até 1 minuto |
| 403 | plan_limit | O pedido passou do que o plano cobre, como um before mais antigo que o histórico | Ajustar o pedido ou subir de plano |
| 404 | not_found | O recurso não existe, como uma API fora do catálogo | Conferir o slug |
| 404 | route_not_found | O endereço não existe | Conferir o endpoint na documentação |
| 429 | rate_limited | Pedidos demais no mesmo minuto | Esperar o Retry-After e desacelerar |
| 429 | too_many_streams | Todas as conexões do /stream estão ocupadas no momento | Tentar de novo em instantes |
| 500 | internal_error | Erro do nosso lado | Tentar de novo com backoff |
| 502 | upstream_error | A fonte não respondeu | Tentar de novo com backoff |
| 504 | timeout | O pedido demorou demais | Tentar de novo com backoff |
Todo erro vem com o mesmo corpo, o que deixa o tratamento curto:
{ "error": { "code": "key_wrong_api", "message": "Esta chave é de outra API." } }Trate pelo code, nunca pela mensagem: o texto muda de idioma e pode ser reescrito, o código não.
O 429 e o Retry-After
Cada plano tem um limite de pedidos por minuto, somado entre todas as chaves do projeto. Quando você passa, a resposta é 429 e vem com os cabeçalhos que dizem exatamente onde você está:
| Cabeçalho | O que diz |
|---|---|
X-RateLimit-Limit | Quantos pedidos o seu plano permite por minuto |
X-RateLimit-Remaining | Quantos sobraram na janela atual |
X-RateLimit-Reset | Quando a janela zera |
Retry-After | Quantos segundos esperar antes do próximo pedido |
A regra é simples: se veio Retry-After, obedeça. Ele não é sugestão, é a resposta certa, e dormir os segundos que ele pede é mais rápido do que insistir e levar 429 de novo.
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")))
continueE o melhor jeito de tratar o 429 é não chegar nele. Três hábitos resolvem:
- Consulte no ritmo do dado, não no seu nervosismo. Numa mesa que roda a cada 34 segundos, consultar o
/latesta cada 3 segundos já é de sobra: são 20 pedidos por minuto num limite de 60. - Mande o
ETag. Guarde oETagda resposta e devolva emIf-None-Match: quando nada mudou, a API responde 304 sem corpo. O pedido ainda conta no limite, mas a rede e o seu processamento caem muito. - Use o
/streamquando der. Ele gasta um pedido na abertura e nada depois, como explicamos em resultados em tempo real.
Backoff exponencial, com jitter
Para os erros temporários sem Retry-After, espere cada vez mais, e com um pouco de aleatoriedade. O exponencial evita martelar um serviço que está tentando levantar; o jitter evita que todos os seus processos voltem no mesmo milissegundo.
from random import random
def espera(tentativa):
"""1s, 2s, 4s, 8s... com até 30% de variação, limitado a 60s."""
return min(60, 2 ** tentativa) * (0.85 + 0.3 * random())Duas regras que acompanham o backoff:
- Tenha um teto. Esperar 2 horas não ajuda ninguém; pare em 30 ou 60 segundos e continue tentando nesse ritmo.
- Não repita o que não é repetível. 400, 401, 403 e 404 não melhoram com espera.
Idempotência: o erro que ninguém vê
Há um erro que não aparece em nenhum status: tratar a mesma rodada duas vezes. Isso acontece quando um pedido dá timeout e você repete, quando o seu processo reinicia, ou quando o event: ready do stream repete a última rodada de propósito.
A solução é a mesma em todos os casos: cada rodada tem um id fixo, e ele é a sua trava.
if rodada["id"] == ultimo_id:
return # já tratamos esta
ultimo_id = rodada["id"]No banco, o mesmo id como chave única transforma uma inserção repetida num conflito silencioso em vez de uma linha duplicada — o assunto do artigo sobre guardar dados em tempo real.
O cliente que trata tudo
Juntando as peças: erro definitivo levanta exceção, erro temporário espera e repete, 429 obedece ao Retry-After.
cliente.py
import time
from random import random
import requests
BASE = "https://api.lynxmetrics.com/v1"
DEFINITIVOS = {400, 401, 402, 403, 404}
class ErroDaApi(Exception):
pass
def pedir(caminho, chave, params=None, tentativas=6):
for tentativa in range(tentativas):
try:
r = requests.get(BASE + caminho, headers={"x-api-key": chave}, params=params, timeout=15)
except requests.RequestException as erro:
print("rede:", erro, flush=True)
else:
if r.status_code == 200:
return r.json()["data"]
if r.status_code in DEFINITIVOS:
codigo = r.json().get("error", {}).get("code", "desconhecido")
raise ErroDaApi(codigo) # avise e pare: repetir não resolve
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
print("temporário:", r.status_code, flush=True) # 500, 502, 504
time.sleep(min(60, 2 ** tentativa) * (0.85 + 0.3 * random()))
raise ErroDaApi("sem resposta depois de " + str(tentativas) + " tentativas")Repare que o 429 não entra no backoff: ele já veio com o tempo certo de espera.
O que registrar, e o que alertar
Um bot silencioso é um bot que você não sabe se está vivo. O mínimo útil:
- Registre todo erro com o
code, o status e a hora. Sem isso, "o bot parou" é uma investigação; com isso, é uma linha de log. - Alerte nos definitivos (401, 402, 403), porque eles exigem uma ação sua e não vão passar sozinhos.
- Conte os temporários em vez de alertar em cada um. Um 502 isolado é vida normal; 502 por dez minutos é problema.
- Vigie o silêncio. Se nenhuma rodada chegou em muito mais tempo do que a mesa costuma levar, algo quebrou, e esse alerta vale mais que todos os outros.
Perguntas frequentes
- O que fazer quando a API devolve 429?
Esperar os segundos que vêm no cabeçalho Retry-After e só então tentar de novo, além de reduzir a frequência das consultas. O 429 significa pedidos demais na mesma janela de um minuto, e os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset mostram quanto sobrou e quando a janela zera.
- Qual a diferença entre erro 401 e 403 numa API?
O 401 é de identificação: a chave não foi enviada, está errada ou foi revogada. O 403 é de permissão: a chave existe, mas não pode acessar aquilo — por exemplo, é de outra API, o teste expirou ou o pedido passou do que o plano cobre. Nenhum dos dois melhora repetindo o pedido.
- O que é backoff exponencial com jitter?
É esperar cada vez mais entre as tentativas (1s, 2s, 4s, 8s...) com uma variação aleatória por cima. O exponencial evita martelar um serviço que está se recuperando, e o jitter evita que vários processos voltem todos no mesmo instante. Use só em erros temporários, e sempre com um teto.
- Como evitar tratar a mesma rodada duas vezes?
Comparando o id da rodada com o último já tratado. O id é fixo e nunca muda, então ele serve de trava no código e de chave única no banco, onde uma reinserção vira conflito em vez de linha duplicada.
Leia também
- O que é uma API e como se conectar a uma pela primeira vez
API explicada sem complicação: o que é, como funcionam REST, JSON e chaves, e como fazer a primeira chamada no navegador, no terminal, em Python e em JavaScript.
- Guardar dados em tempo real: do JSON ao banco, sem perder
Como armazenar os dados que chegam de uma API ao vivo: chave única, upsert, fuso horário, detecção de buracos e o backfill que fecha a janela fora do ar.
- Como lemos uma mesa ao vivo: do vídeo ao JSON
O caminho que um resultado faz da mesa até a API: segmentos de vídeo, rede neural, a conferência pelas regras do jogo e por que descartamos em vez de chutar.