Errores, límites de tasa y fiabilidad
El código de producción se comunica con un servicio de red, así 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.)
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: respeta retry-after, suaviza los picos, agrupa en lotes el trabajo offline y usa un modelo más barato (Elegir un modelo) 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.