Blog · Geral

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

StatusCódigoO que aconteceuO que fazer
400bad_requestUm parâmetro com formato inválido, como um before ou after que não é data ISO 8601 nem id de rodadaCorrigir a chamada
401unauthorizedA chave não foi enviada, está errada ou foi revogadaConferir o cabeçalho x-api-key e copiar a chave de novo no painel
403key_wrong_apiA chave é de outra API do catálogoUsar a chave da API certa; cada chave abre uma só
403trial_expiredO prazo do teste grátis acabouAssinar o projeto ou abrir um teste novo depois de 24 horas
403subscription_requiredO projeto não tem assinatura ativaReativar no painel
402payment_pendingO pagamento não entrou (cartão recusado, Pix vencido)Pagar; as chaves voltam sozinhas em até 1 minuto
403plan_limitO pedido passou do que o plano cobre, como um before mais antigo que o históricoAjustar o pedido ou subir de plano
404not_foundO recurso não existe, como uma API fora do catálogoConferir o slug
404route_not_foundO endereço não existeConferir o endpoint na documentação
429rate_limitedPedidos demais no mesmo minutoEsperar o Retry-After e desacelerar
429too_many_streamsTodas as conexões do /stream estão ocupadas no momentoTentar de novo em instantes
500internal_errorErro do nosso ladoTentar de novo com backoff
502upstream_errorA fonte não respondeuTentar de novo com backoff
504timeoutO pedido demorou demaisTentar 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çalhoO que diz
X-RateLimit-LimitQuantos pedidos o seu plano permite por minuto
X-RateLimit-RemainingQuantos sobraram na janela atual
X-RateLimit-ResetQuando a janela zera
Retry-AfterQuantos 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")))
    continue

E 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 /latest a cada 3 segundos já é de sobra: são 20 pedidos por minuto num limite de 60.
  • Mande o ETag. Guarde o ETag da resposta e devolva em If-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 /stream quando 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