Blog · General

Errores y límites de API: 429, backoff y qué hacer

Guía práctica de los errores de una API de datos: qué significa cada estado HTTP, cómo tratar el 429 con Retry-After y backoff, y el código que lo resuelve.

Publicado el 30 de octubre de 2026 · 7 min de lectura

La diferencia entre un bot que corre meses solo y uno que se cae cada semana casi nunca está en el código elegante: está en el tratamiento de errores. Una API de datos en vivo te va a devolver 429 en algún momento, tu conexión va a oscilar, y el servidor del otro lado va a reiniciarse. Esta guía muestra qué significa cada error, qué hacer con él y, al final, un cliente en Python que los trata todos de una vez.

Los ejemplos usan la API de LynxMetrics, pero los códigos HTTP y los patrones valen para cualquier API REST. Si "estado HTTP" y "cabecera" todavía son novedad, empezá por la guía qué es una API y cómo conectarse a una.

Los dos tipos de error

Separalos desde el principio, porque el tratamiento es opuesto:

  • Error tuyo, que no mejora solo (400, 401, 403, 404): repetir el mismo pedido devuelve el mismo error. El programa debe parar y avisar, no insistir.
  • Error temporal (429, 500, 502, 504, falla de red): el mismo pedido puede funcionar en unos segundos. Acá sí vale esperar y reintentar.

Un bucle que repite un 401 mil veces por minuto es la forma más rápida de quemar tu límite sin recibir un solo dato.

Los códigos, uno por uno

EstadoCódigoQué pasóQué hacer
400bad_requestUn parámetro con formato inválido, como un before o after que no es una fecha ISO 8601 ni un id de rondaCorregir la llamada
401unauthorizedLa clave no fue enviada, está mal o fue revocadaRevisar la cabecera x-api-key y copiar la clave de nuevo en el panel
403key_wrong_apiLa clave es de otra API del catálogoUsar la clave de la API correcta; cada clave abre una sola
403trial_expiredEl plazo de la prueba gratis terminóSuscribir el proyecto o abrir una prueba nueva después de 24 horas
403subscription_requiredEl proyecto no tiene suscripción activaReactivarlo en el panel
402payment_pendingEl pago no entró (tarjeta rechazada, Pix vencido)Pagar; las claves vuelven solas en hasta 1 minuto
403plan_limitEl pedido pasó de lo que cubre el plan, como un before más antiguo que el historialAjustar el pedido o subir de plan
404not_foundEl recurso no existe, como una API fuera del catálogoRevisar el slug
404route_not_foundLa dirección no existeRevisar el endpoint en la documentación
429rate_limitedDemasiadas peticiones en el mismo minutoEsperar el Retry-After y desacelerar
429too_many_streamsTodas las conexiones del /stream están ocupadas en este momentoProbar de nuevo en instantes
500internal_errorError de nuestro ladoReintentar con backoff
502upstream_errorLa fuente no respondióReintentar con backoff
504timeoutEl pedido tardó demasiadoReintentar con backoff

Todo error viene con el mismo cuerpo, lo que deja el tratamiento corto:

{ "error": { "code": "key_wrong_api", "message": "Esta clave es de otra API." } }

Tratalo por el code, nunca por el mensaje: el texto cambia de idioma y puede reescribirse, el código no.

El 429 y el Retry-After

Cada plan tiene un límite de peticiones por minuto, sumado entre todas las claves del proyecto. Cuando lo pasás, la respuesta es 429 y viene con las cabeceras que dicen exactamente dónde estás:

CabeceraQué dice
X-RateLimit-LimitCuántas peticiones permite tu plan por minuto
X-RateLimit-RemainingCuántas quedan en la ventana actual
X-RateLimit-ResetCuándo se reinicia la ventana
Retry-AfterCuántos segundos esperar antes del próximo pedido

La regla es simple: si vino Retry-After, obedecelo. No es una sugerencia, es la respuesta correcta, y dormir los segundos que pide es más rápido que insistir y llevarte otro 429.

if r.status_code == 429:
    time.sleep(int(r.headers.get("Retry-After", "5")))
    continue

Y la mejor forma de tratar el 429 es no llegar a él. Tres hábitos lo resuelven:

  • Consultá al ritmo del dato, no al de tu ansiedad. En una mesa que corre una ronda cada 34 segundos, consultar el /latest cada 3 segundos ya sobra: son 20 peticiones por minuto en un límite de 60.
  • Mandá el ETag. Guardá el ETag de la respuesta y devolvelo en If-None-Match: cuando nada cambió, la API responde 304 sin cuerpo. La petición sigue contando en el límite, pero el tráfico y tu procesamiento bajan mucho.
  • Usá el /stream cuando puedas. Gasta una petición al abrir y nada después, como explicamos en resultados en tiempo real.

Backoff exponencial, con jitter

Para los errores temporales sin Retry-After, esperá cada vez más, y con algo de aleatoriedad. Lo exponencial evita martillar un servicio que está intentando levantarse; el jitter evita que todos tus procesos vuelvan en el mismo milisegundo.

from random import random

def espera(intento):
    """1s, 2s, 4s, 8s... con hasta 30% de variación, limitado a 60s."""
    return min(60, 2 ** intento) * (0.85 + 0.3 * random())

Dos reglas que acompañan al backoff:

  • Tené un techo. Esperar 2 horas no ayuda a nadie; parate en 30 o 60 segundos y seguí intentando a ese ritmo.
  • No repitas lo que no es repetible. 400, 401, 403 y 404 no mejoran con espera.

Idempotencia: el error que nadie ve

Hay un error que no aparece en ningún estado: tratar la misma ronda dos veces. Pasa cuando un pedido da timeout y lo repetís, cuando tu proceso se reinicia, o cuando el event: ready del stream repite la última ronda a propósito.

La solución es la misma en todos los casos: cada ronda tiene un id fijo, y ese es tu traba.

if ronda["id"] == ultimo_id:
    return            # ya tratamos esta
ultimo_id = ronda["id"]

En la base, el mismo id como clave única transforma una inserción repetida en un conflicto silencioso en vez de una fila duplicada — el tema del artículo sobre guardar datos en tiempo real.

El cliente que trata todo

Juntando las piezas: error definitivo levanta excepción, error temporal espera y reintenta, y el 429 obedece al 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 ErrorDeApi(Exception):
    pass


def pedir(camino, clave, params=None, intentos=6):
    for intento in range(intentos):
        try:
            r = requests.get(BASE + camino, headers={"x-api-key": clave}, params=params, timeout=15)
        except requests.RequestException as error:
            print("red:", error, 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", "desconocido")
                raise ErrorDeApi(codigo)                      # avisá y pará: repetir no resuelve
            if r.status_code == 429:
                time.sleep(int(r.headers.get("Retry-After", "5")))
                continue
            print("temporal:", r.status_code, flush=True)      # 500, 502, 504
        time.sleep(min(60, 2 ** intento) * (0.85 + 0.3 * random()))
    raise ErrorDeApi("sin respuesta después de " + str(intentos) + " intentos")

Fijate que el 429 no entra en el backoff: ya vino con el tiempo correcto de espera.

Qué registrar, y qué alertar

Un bot silencioso es un bot que no sabés si está vivo. El mínimo útil:

  • Registrá todo error con el code, el estado y la hora. Sin eso, "el bot se detuvo" es una investigación; con eso, es una línea de log.
  • Alertá en los definitivos (401, 402, 403), porque exigen una acción tuya y no van a pasar solos.
  • Contá los temporales en vez de alertar en cada uno. Un 502 aislado es vida normal; 502 por diez minutos es un problema.
  • Vigilá el silencio. Si no llegó ninguna ronda en mucho más tiempo del que la mesa suele tardar, algo se rompió, y esa alerta vale más que todas las otras.

Preguntas frecuentes

¿Qué hacer cuando la API devuelve 429?

Esperar los segundos que vienen en la cabecera Retry-After y solo entonces reintentar, además de reducir la frecuencia de las consultas. El 429 significa demasiadas peticiones en la misma ventana de un minuto, y las cabeceras X-RateLimit-Remaining y X-RateLimit-Reset muestran cuánto queda y cuándo se reinicia la ventana.

¿Cuál es la diferencia entre el error 401 y el 403 en una API?

El 401 es de identificación: la clave no fue enviada, está mal o fue revocada. El 403 es de permiso: la clave existe, pero no puede acceder a eso — por ejemplo es de otra API, la prueba expiró o el pedido pasó de lo que cubre el plan. Ninguno de los dos mejora repitiendo el pedido.

¿Qué es el backoff exponencial con jitter?

Es esperar cada vez más entre los intentos (1s, 2s, 4s, 8s...) con una variación aleatoria encima. Lo exponencial evita martillar un servicio que se está recuperando, y el jitter evita que varios procesos vuelvan en el mismo instante. Usalo solo en errores temporales, y siempre con un techo.

¿Cómo evito tratar la misma ronda dos veces?

Comparando el id de la ronda con el último ya tratado. El id es fijo y nunca cambia, así que sirve de traba en el código y de clave única en la base, donde una reinserción se vuelve conflicto en vez de fila duplicada.

Lee también