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
| Estado | Código | Qué pasó | Qué hacer |
|---|---|---|---|
| 400 | bad_request | Un parámetro con formato inválido, como un before o after que no es una fecha ISO 8601 ni un id de ronda | Corregir la llamada |
| 401 | unauthorized | La clave no fue enviada, está mal o fue revocada | Revisar la cabecera x-api-key y copiar la clave de nuevo en el panel |
| 403 | key_wrong_api | La clave es de otra API del catálogo | Usar la clave de la API correcta; cada clave abre una sola |
| 403 | trial_expired | El plazo de la prueba gratis terminó | Suscribir el proyecto o abrir una prueba nueva después de 24 horas |
| 403 | subscription_required | El proyecto no tiene suscripción activa | Reactivarlo en el panel |
| 402 | payment_pending | El pago no entró (tarjeta rechazada, Pix vencido) | Pagar; las claves vuelven solas en hasta 1 minuto |
| 403 | plan_limit | El pedido pasó de lo que cubre el plan, como un before más antiguo que el historial | Ajustar el pedido o subir de plan |
| 404 | not_found | El recurso no existe, como una API fuera del catálogo | Revisar el slug |
| 404 | route_not_found | La dirección no existe | Revisar el endpoint en la documentación |
| 429 | rate_limited | Demasiadas peticiones en el mismo minuto | Esperar el Retry-After y desacelerar |
| 429 | too_many_streams | Todas las conexiones del /stream están ocupadas en este momento | Probar de nuevo en instantes |
| 500 | internal_error | Error de nuestro lado | Reintentar con backoff |
| 502 | upstream_error | La fuente no respondió | Reintentar con backoff |
| 504 | timeout | El pedido tardó demasiado | Reintentar 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:
| Cabecera | Qué dice |
|---|---|
X-RateLimit-Limit | Cuántas peticiones permite tu plan por minuto |
X-RateLimit-Remaining | Cuántas quedan en la ventana actual |
X-RateLimit-Reset | Cuándo se reinicia la ventana |
Retry-After | Cuá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")))
continueY 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
/latestcada 3 segundos ya sobra: son 20 peticiones por minuto en un límite de 60. - Mandá el
ETag. Guardá elETagde la respuesta y devolvelo enIf-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
/streamcuando 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
- Qué es una API y cómo conectarse a una por primera vez
API explicada sin complicaciones: qué es, cómo funcionan REST, JSON y las claves, y cómo hacer la primera llamada en el navegador, la terminal, Python y JavaScript.
- Guardar datos en tiempo real: del JSON a la base
Cómo almacenar lo que llega de una API en vivo: clave única, upsert, huso horario, detección de huecos y el backfill que cierra la ventana caída.
- Cómo leemos una mesa en vivo: del video al JSON
El camino de un resultado de la mesa a la API: segmentos de video, red neuronal, la verificación por las reglas del juego y por qué descartamos antes que adivinar.