Estrategia de conmutación por error para API de IA: matriz de fallos

Política por fases para decidir cuándo reintentar, usar una ruta con el mismo contrato, detenerse, conciliar efectos secundarios o investigar.

Estrategia de conmutación por error para API de IA: matriz de fallos

Un reintento de una API de IA, un cambio de ruta y una sustitución de modelo son acciones distintas. El reintento repite una tentativa bajo el mismo contrato. El cambio de ruta envía el modelo y el protocolo solicitados por otro camino válido. La sustitución cambia el modelo y puede alterar la calidad, el precio, la latencia, el comportamiento de las herramientas, los límites de contexto y el formato de salida.

Una política fiable decide qué acciones están permitidas antes del incidente. La decisión depende de la clase de fallo, de si ya se entregó una respuesta, de la idempotencia de la operación completa y del número de intentos que aún caben en el plazo límite del usuario.

Separar reintentos, cambios de ruta y sustituciones de modelo

Usa nombres distintos en la configuración, los registros y los manuales operativos.

Acción Qué cambia Cuándo resulta útil Riesgo principal
Reintento en la misma ruta Tiempo y número de intento Recuperar un fallo transitorio breve de la misma ruta Añadir carga a una dependencia con problemas
Ruta alternativa con el mismo contrato Canal del proveedor, cuenta o grupo ordenado Mantener el modelo y el protocolo cuando falla un camino Incompatibilidad oculta entre rutas supuestamente equivalentes
Sustitución de modelo ID del modelo o política de modelos Compromiso de calidad, coste o disponibilidad aprobado por producto Cambios silenciosos de comportamiento y facturación

No llames «reintento» a las tres cosas. El equipo de operaciones debe saber si una solicitud se repitió, cambió de ruta o fue respondida por otro modelo. Para el usuario, sustituir el modelo debe ser un contrato explícito, no un atajo invisible de recuperación.

Algunas pasarelas permiten ordenar pasos por proveedor o modelo. Por ejemplo, la documentación de rutas alternativas de Cloudflare indica qué paso produjo la respuesta final. La lección no es copiar una política concreta, sino conservar pruebas de cada intento siempre que cambie la ruta.

Aplicar cuatro comprobaciones antes de repetir una solicitud

Un código de estado no constituye por sí solo una política de reintentos. Evalúa cuatro aspectos:

  1. Clase de fallo: ¿el fallo es transitorio, permanente, causado por quien llama o de resultado ambiguo?
  2. Fase de la respuesta: ¿ocurrió antes de las cabeceras, antes de una salida efectiva o después de entregar contenido?
  3. Idempotencia: ¿puede repetirse la operación completa sin duplicar un efecto externo?
  4. Presupuesto de intentos: ¿queda tiempo real y un intento disponible?

La estrategia de reintentos de Google Cloud plantea las mismas dos distinciones para las API generales: la respuesta indica si repetir podría servir y la idempotencia determina si es seguro. Los errores 408, 429, 5xx, los tiempos de espera del socket y las desconexiones suelen ser transitorios, pero las operaciones no idempotentes exigen condiciones más estrictas.

En un flujo de trabajo de IA, la idempotencia va más allá de la llamada HTTP al modelo. Repetir una instrucción puede volver a proponer un correo electrónico, un reembolso, un despliegue o una escritura en la base de datos. Cada ejecución de una herramienta necesita una clave de idempotencia estable y un resultado persistido, aunque la inferencia sea de solo lectura.

Empezar por una matriz de fallos

Esta matriz propone una política conservadora en la aplicación. La pasarela puede haber cambiado internamente a otra ruta con el mismo contrato antes de entregar el resultado final; coordina ambas capas para no multiplicar intentos.

Fallo o fase Reintento en la misma ruta Ruta alternativa con el mismo contrato Detener o investigar Motivo
Error de validación, campo no admitido o solicitud mal formada No No Corregir la solicitud Repetir el mismo contrato inválido no puede funcionar
Error de autenticación, autorización, cuota o política en la pasarela No No Corregir la cuenta o la política Otra ruta no debe eludir una decisión de la pasarela
Fallo de credencial o cuenta del proveedor antes de la salida No en la ruta fallida Sí, con otro canal verificado Aislar e investigar el canal El contrato puede mantenerse al retirar una credencial con problemas
Fallo de red o 408 antes de la salida Como máximo un intento acotado si es idempotente Sí Detener al llegar al plazo límite El fallo es transitorio, pero tras una desconexión el resultado puede ser ambiguo
429 antes de la salida Reintento diferido respetando Retry-After Sí, si otra ruta tiene capacidad Detener al agotar el presupuesto Repetir de inmediato agrava la limitación de solicitudes
500, 502, 503 o 504 antes de la salida Reintento acotado con espera progresiva Sí Investigar fallos repetidos Suelen ser transitorios, pero no demuestran que todas las rutas sean seguras
Respuesta del proveedor incompatible con el esquema antes de la salida al cliente Normalmente no Solo hacia una ruta validada para ese esquema Aislar o investigar la compatibilidad Repetir la misma implementación incompatible rara vez ayuda
Rechazo del modelo o respuesta conforme a la política de seguridad No No Devolver el resultado Un rechazo válido no es una caída de infraestructura
Cancelación de quien llama o 499 del receptor No No Detener de inmediato Quien llama ya no necesita el trabajo
Flujo parcial después de entregar texto o argumentos de herramienta Sin repetición transparente Sin cambio transparente de ruta Marcarlo como parcial y delegar en la aplicación Otro flujo puede duplicar o contradecir contenido ya entregado
Efecto de una herramienta con estado final desconocido No hasta conciliar No hasta conciliar Consultar el registro idempotente o el sistema externo Otra inferencia puede proponer el mismo efecto

La fase importa: un 503 antes de cualquier salida no equivale a una conexión cerrada cuando ya se mostraron 400 tokens.

Tratar el inicio del flujo como punto de compromiso

Antes de que empiece la salida hacia el cliente, una pasarela puede descartar el intento fallido y probar otra ruta sin mostrar dos respuestas. Después del primer byte con contenido significativo, la repetición transparente deja de ser segura.

Reiniciar el flujo puede:

  • repetir el comienzo;
  • generar una continuación distinta;
  • emitir la misma llamada a función con un identificador nuevo;
  • cambiar el consumo y el coste sin un límite visible;
  • impedir que el cliente sepa a qué intento pertenece cada evento.

Si un flujo se interrumpe después de empezar, devuelve un error de resultado parcial o de transporte con el ID de solicitud original. La aplicación puede ofrecer «reintentar», continuar desde un punto de control seguro o descartar el resultado parcial. No debe unir un flujo nuevo al anterior como si fueran una sola respuesta.

En las llamadas a funciones, conserva los identificadores aceptados y sus efectos antes de que un reintento pueda recrearlos. La comparación de formatos de llamadas a funciones explica cómo combinar esos identificadores con la idempotencia de la aplicación.

Acotar la espera progresiva por intentos y tiempo total

La espera exponencial separa los intentos en el tiempo; una variación aleatoria evita que miles de clientes vuelvan a la vez después de una caída compartida.

delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)

Respeta un Retry-After válido si cabe en el plazo límite. La espera progresiva no autoriza el reintento: antes deben superarse las comprobaciones de fallo e idempotencia.

Define un presupuesto total, no solo un contador:

  • máximo de intentos por acción;
  • tiempo total, incluida la cola y la espera progresiva;
  • intentos antes y después de seleccionar un grupo alternativo;
  • tiempo mínimo restante para producir una respuesta útil;
  • propagación de cancelación a todos los intentos activos.

En una solicitud interactiva con un plazo de 15 segundos, tres intentos de 10 segundos no forman una política viable. Un trabajo por lotes puede tener más margen, pero también necesita un plazo final y un identificador persistente de tarea.

Evitar la amplificación de reintentos entre capas

Si el SDK ejecuta tres intentos, la pasarela prueba tres rutas por cada uno y el proxy del proveedor hace dos llamadas por ruta:

3 intentos del cliente × 3 intentos de la pasarela × 2 intentos al proveedor = 18 llamadas al proveedor

Una acción del usuario se convierte en 18 llamadas. Durante un incidente aumentan las colas, los límites de solicitudes, el coste y el tiempo de recuperación.

Asigna la responsabilidad de los reintentos:

  • la pasarela gestiona el cambio inmediato a otro canal con el mismo contrato;
  • la aplicación decide si puede repetirse la acción completa;
  • los reintentos automáticos del SDK se desactivan o acotan cuando la pasarela ya reintenta;
  • los trabajos asíncronos usan un identificador persistente y un registro de intentos;
  • ninguna capa inicia un intento después de que quien llama cancele la operación.

Registra tanto el número de intento de cada capa como un ID estable de extremo a extremo. De otro modo, cada componente aparenta haber hecho dos o tres intentos mientras la amplificación combinada queda oculta.

Verificar que la ruta alternativa conserva el contrato

Compartir un nombre público de modelo no garantiza el mismo comportamiento. Antes de incluir un canal en un cambio de ruta transparente, exige pruebas:

Área Evidencia necesaria
Identidad del modelo El modelo solicitado existe sin una asignación silenciosa a otro modelo
Endpoint La solicitud de Responses o Chat Completions se acepta tal como está configurada
Transmisión Los tipos de evento, la finalización, el consumo y la cancelación funcionan
Salida estructurada Funcionan el subconjunto necesario de JSON Schema y el modo estricto
Llamadas a funciones Las herramientas, los ID de llamada, los argumentos transmitidos y los resultados completan el recorrido de ida y vuelta
Límites El contexto, la salida, la tasa y la concurrencia encajan con la carga de trabajo
Errores Los estados y cuerpos de error pueden clasificarse sin revelar secretos
Consumo y coste Están definidos los tokens, los campos de caché, el nivel de servicio y la política de precios
Seguridad y región La política, la ruta de los datos y los requisitos de residencia siguen cumpliéndose

Si una ruta falla en un requisito obligatorio, no es una alternativa transparente para esa carga de trabajo. Puede usarse bajo otra política explícita.

Cambiar de modelo siempre requiere una decisión de producto: modelos permitidos, calidad mínima, precio máximo, contrato de herramientas y comunicación al usuario. No cambies silenciosamente a un modelo más barato o menos capaz por un error de ruta.

Entender cómo cambia de ruta Modelflare

Modelflare busca rutas válidas para el modelo solicitado. Una clave de API normal tiene un grupo principal y puede incluir una lista ordenada de grupos alternativos. Una clave de API inteligente evalúa los grupos disponibles según su estrategia de enrutamiento. Ninguno de los mecanismos debe sustituir silenciosamente el modelo.

La admisión por RPM del grupo ocurre antes de la facturación y de la llamada al proveedor. Si el grupo está lleno, se evalúa otro grupo alternativo o un candidato del enrutamiento inteligente; si no hay grupos válidos, se responde 429.

Dentro del grupo, la prioridad del canal marca el orden de cambio de cuenta. Tras un error del proveedor, el canal se excluye y la selección continúa. El cambio de canal actual no depende de RetryTimes ni de AutomaticRetryStatusCodes; termina al lograr el resultado, agotar las rutas, recibir una cancelación o cuando la salida ya ha comenzado y no puede repetirse de forma transparente.

Estas decisiones internas de ruta para el mismo modelo no autorizan al cliente a añadir un bucle ilimitado. Consulta Enrutamiento fiable de API de IA para diseñar grupos y canales, y Diagnóstico de errores de API de IA para separar errores de política y fallos del proveedor.

Conservar evidencia de cada intento

Un 200 final no demuestra que la primera ruta funcionara. El ID del canal final tampoco describe los intentos fallidos. Conserva como mínimo:

  • ID de solicitud estable e ID de correlación visible para quien llama;
  • secuencia de intentos y referencias de grupo/canal;
  • modelo y contrato del endpoint de cada intento;
  • estado, clase de error y fase del flujo;
  • si la salida hacia el cliente había comenzado;
  • hitos temporales y estado de cancelación;
  • consumo de entrada, salida y tokens en caché cuando esté disponible;
  • coste de cada intento completado o facturable;
  • motivo final: éxito, rutas agotadas, cancelación, resultado parcial o detención por política.

No almacenes claves de API, instrucciones o respuestas en bruto ni credenciales del proveedor solo para investigar cambios de ruta. Normalmente bastan las clases de error sin datos sensibles y los tiempos; reserva archivos breves y restringidos de solicitudes para investigaciones habilitadas de forma explícita.

Ensayar la política antes de producción

Ejecuta el protocolo real con entradas seguras y deterministas:

  1. deshabilita el canal principal antes de las cabeceras y verifica la siguiente ruta para el mismo modelo;
  2. devuelve una limitación de solicitudes y comprueba los límites de intentos y Retry-After;
  3. cancela la llamada y demuestra que no empieza otro intento;
  4. interrumpe el flujo tras producir salida y demuestra que no hay repetición transparente;
  5. envía una solicitud no válida y confirma que el cambio de ruta no la oculta;
  6. repite un flujo de herramientas y confirma un solo efecto externo;
  7. agota todas las rutas y verifica un único error terminal;
  8. revisa el registro de intentos y concilia el consumo y el coste.

Despliega primero en una carga de trabajo pequeña. Mide por separado el número de intentos, el éxito después de cambiar de ruta y la tasa bruta de éxito, y conserva una forma rápida de retirar rutas con problemas. El objetivo no es maximizar los cambios de ruta, sino recuperarse de forma segura dentro de un plazo limitado, conservar el contrato del modelo y dejar pruebas de cada intento.