Errores, límites de tasa y fiabilidad
- Leer el mapa de errores HTTP y saber qué estados reintentar frente a cuáles corregir
- Reintentar errores transitorios con backoff exponencial y jitter, acotado
- Gestionar los límites de tasa con retry-after, suavizado, procesamiento por lotes y modelos más baratos
- Aislar tu código de las obsolescencias y migraciones de modelos
El código de producción se comunica con un servicio de red, por lo que debe esperar fallos. Un poco de estructura aquí marca la diferencia entre una integración inestable y una fiable.
El mapa de errores
Estados HTTP típicos que tendrás que gestionar:
| Estado | Significado | Qué hacer |
|---|---|---|
| 400 | Solicitud no válida | Corrige el payload; no reintentes tal cual |
| 401 | Clave de API incorrecta/ausente | Comprueba las credenciales |
| 403 | No permitido | Comprueba el acceso/los permisos |
| 429 | Límite de tasa alcanzado | Aplica backoff y reintenta (respeta retry-after) |
| 500/529 | Error del servidor / sobrecargado | Reintenta con backoff |
- Los SDK exponen estos casos como excepciones tipadas, de modo que puedes ramificar de forma limpia en lugar de analizar cadenas de texto.
Reintentos con backoff
Para errores transitorios (429, 5xx), reintenta con backoff exponencial + jitter, con tope:
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
- Muchos SDK reintentan los errores transitorios automáticamente: conoce el comportamiento por defecto de tu cliente antes de añadir el tuyo, o podrías duplicar los reintentos.
Límites de tasa
Los límites se aplican por cuenta/nivel (solicitudes y tokens por minuto). Cuando alcanzas uno recibes un 429 con pistas de tiempo. Estrategias para mantenerte bajo el techo:
Guided walkthrough1 of 4
- Cuando recibas un 429, lee la pista de tiempo en la respuesta y espera ese intervalo antes de reintentar.
- Reparte las solicitudes a lo largo del tiempo en lugar de dispararlas todas a la vez.
- Mueve los trabajos de alto volumen y no interactivos al procesamiento por lotes.
- Enruta los pasos de alto volumen a un modelo más barato: consulta Elegir un modelo.
Consulta Elegir un modelo para seleccionar el modelo adecuado para los pasos de alto volumen.
Migración de modelos
Los IDs de modelo llevan fecha/versión y acaban quedando obsoletos. Protégete:
- Lee el ID del modelo desde la configuración, no de literales dispersos.
- Vigila las obsolescencias: consulta Seguimiento de obsolescencias y migración y la tabla de modelos.
- Vuelve a ejecutar tus evaluaciones cuando cambies de modelo.
- 400/401/403 son culpa tuya: corrige la solicitud o las credenciales, no reintentes a ciegas. 429 y 500/529 son reintentables.
- Reintenta los errores transitorios con backoff exponencial + jitter, con tope (p. ej. min(2 ** attempt + random(), 30)).
- Ante un 429: respeta retry-after, suaviza los picos, agrupa en lotes el trabajo offline y enruta los pasos de alto volumen a un modelo más barato.
- Lee los IDs de modelo desde la configuración, vigila las obsolescencias y vuelve a ejecutar las evaluaciones al migrar de modelo.