Fallos en las API de IA en producción
Los mensajes de error rara vez cuentan la historia completa cuando tu función de IA falla a las 2 AM. He gestionado integraciones con OpenAI y Anthropic durante un año. Aprendí a agrupar los fallos según lo que significan para la depuración.
Gestión de límites de tasa (Rate Limits)
Los errores 429 de OpenAI tienen diferentes causas. Debes comprobar el código de error para saber cómo reaccionar.
- Los límites de solicitudes por minuto (RPM) se recuperan en segundos.
- Los límites de tokens por minuto (TPM) se recuperan en 60 segundos.
- El agotamiento de la cuota mensual permanece bloqueado hasta que añadas créditos o se reinicie el ciclo de facturación.
No utilices retroceso exponencial (exponential backoff) para problemas de cuota. Perderás el tiempo.
Los errores 529 de Anthropic significan que el proveedor está sobrecargado. Trata esto como un error 503. El problema está de su lado. Retrocede y alerta a tu equipo.
Gestión de errores 400
Estos fallos suelen ser culpa tuya. Presta atención a estos tres patrones:
- Desajustes en la versión del modelo. Actualizaste un nombre en un lugar pero no en tu manejador de reintentos (retry handler).
- Desbordamiento de la ventana de contexto. El historial de la conversación creció demasiado. Esto suele ocurrir debido a una lógica de truncamiento incorrecta.
- Fallos de validación de esquema. Tu estructura JSON tiene tipos no soportados o referencias recursivas.
Para solucionar esto, registra el payload completo de la solicitud para los errores 400. Primero anonimiza los datos del usuario. El cuerpo de la respuesta te indica exactamente qué campo falló.
Gestión de tiempos de espera (Timeouts)
Los timeouts son difíciles de rastrear porque el proveedor no ve nada malo.
- Connect timeout. El handshake falló. Esto ocurre durante interrupciones del proveedor o problemas de DNS. Comprueba tu red de salida.
- Read timeout. El modelo comenzó pero no terminó. Tu aplicación debe manejar salidas de streaming parciales.
- Gateway timeout (504). Tu proxy agotó el tiempo primero. Es posible que la solicitud aún se esté ejecutando en el proveedor. Utiliza la deduplicación antes de reintentar.
Para depurar, separa tu connect timeout de tu read timeout. Registra el time-to-first-token para encontrar dónde reside la latencia.
Gestión de problemas del proveedor
- Un error 500 a menudo se resuelve con un reintento tras dos segundos.
- Un error 503 significa que el servicio está degradado. Si la página de estado del proveedor muestra un incidente, utiliza un circuit breaker.
- Registra siempre qué versión del modelo falló. Los diferentes modelos tienen diferentes niveles de fiabilidad.
Deja de saltar de los registros a Slack. Consulta primero la página de estado del proveedor. Te ahorrará 20 minutos de pánico.
Comunidad de aprendizaje opcional: https://t.me/GyaanSetuAi