Estrategia de fallback de AI API: matriz de fallos de proveedores

Un retry de AI API, un fallback de ruta y una sustitución de modelo son acciones distintas. El retry repite un intento bajo el mismo contrato. El fallback envía el modelo y el protocolo solicitados a otra ruta elegible. La sustitución cambia el modelo y puede alterar calidad, precio, latencia, Tools, Context Limits y 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 deadline del usuario.

Separar retry, fallback y sustitución de modelo

Usa nombres distintos en configuración, logs y runbooks.

Acción	Qué cambia	Cuándo resulta útil	Riesgo principal
Same-route retry	Tiempo y número de intento	Recuperar un fallo transitorio breve de la misma ruta	Añadir carga a una dependencia no saludable
Same-contract fallback	Canal upstream, cuenta o grupo ordenado	Mantener modelo y protocolo cuando falla un camino	Incompatibilidad oculta entre rutas supuestamente equivalentes
Model substitution	Model ID o política de modelos	Trade-off de calidad, coste o disponibilidad aprobado por producto	Cambios silenciosos de comportamiento y facturación

No llames “retry” a las tres cosas. Operaciones debe saber si una petición 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.

Algunos gateways permiten ordenar pasos por proveedor o modelo. Por ejemplo, la documentación de fallback de Cloudflare indica qué paso produjo la respuesta final. La lección no es copiar una política concreta, sino conservar evidencia por intento cada vez que cambia la ruta.

Aplicar cuatro gates antes de repetir una petición

Un Status Code no constituye por sí solo una Retry Policy. Evalúa cuatro gates:

1. Failure Class: ¿el fallo es transitorio, permanente, causado por el caller o ambiguo?
2. Response Phase: ¿ocurrió antes de headers, antes de output efectivo o después de entregar output?
3. Idempotency: ¿puede repetirse la operación completa sin duplicar un efecto externo?
4. Attempt Budget: ¿queda tiempo real y un intento disponible?

La estrategia de retry de Google Cloud plantea las mismas dos distinciones para APIs generales: la respuesta indica si repetir podría servir y la idempotencia determina si es seguro. 408, 429, 5xx, Socket Timeout y Disconnect suelen ser transitorios, pero las operaciones no idempotentes exigen condiciones más estrictas.

En un AI Workflow, la idempotencia va más allá de la llamada HTTP al modelo. Repetir un Prompt puede volver a proponer un email, un reembolso, un despliegue o una escritura en base de datos. Cada ejecución de Tool necesita una Idempotency Key estable y un resultado persistido, aunque la inferencia sea de solo lectura.

Empezar por una Failure Matrix

Esta matriz propone una política conservadora de aplicación. El gateway puede haber ejecutado un same-contract failover interno antes de entregar el resultado terminal; coordina ambas capas para no multiplicar intentos.

Fallo o fase	Same-route retry	Same-contract fallback	Detener o investigar	Motivo
Error de validación, campo no soportado o request malformada	No	No	Corregir request	Repetir el mismo contrato inválido no puede funcionar
Authentication, authorization, quota o policy denial del gateway	No	No	Corregir cuenta o policy	Otra ruta no debe eludir una decisión del gateway
Fallo de credencial o cuenta upstream antes del output	No en la ruta fallida	Sí, con otro canal verificado	Aislar e investigar el canal	El contrato puede mantenerse retirando una credencial no saludable
Network failure o 408 antes del output	Como máximo un intento acotado si es idempotente	Sí	Detener al llegar al deadline	El fallo es transitorio, pero tras un disconnect el resultado puede ser ambiguo
429 antes del output	Retry diferido respetando Retry-After	Sí, si otra ruta tiene capacidad	Detener al agotar budget	Repetir de inmediato amplifica el rate limit
500, 502, 503 o 504 antes del output	Retry acotado con backoff	Sí	Investigar fallos repetidos	Suelen ser transitorios, pero no prueban que toda ruta sea segura
Respuesta del proveedor inválida contra Schema antes del output downstream	Normalmente no	Solo hacia una ruta validada para ese Schema	Aislar o investigar compatibilidad	Repetir la misma implementación incompatible rara vez ayuda
Refusal del modelo o completion segura	No	No	Devolver el resultado	Un refusal válido no es una caída de infraestructura
Cancelación del caller o downstream 499	No	No	Detener de inmediato	El caller ya no quiere el trabajo
Stream parcial después de entregar texto o Tool Arguments	Sin replay transparente	Sin fallback transparente	Marcar Partial y delegar en la aplicación	Otro stream puede duplicar o contradecir output ya entregado
Efecto de Tool con estado de finalización desconocido	No hasta reconciliar	No hasta reconciliar	Consultar registro idempotente o sistema externo	Otra inferencia puede proponer el mismo efecto

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

Tratar el inicio del stream como Commit Boundary

Antes de que empiece el output downstream, un gateway puede descartar el intento fallido y probar otra ruta sin enseñar dos respuestas. Después del primer byte con contenido significativo, el replay transparente deja de ser seguro.

Reiniciar el stream puede:

• repetir el comienzo;
• generar una continuación distinta;
• emitir la misma Function Call con un Call ID nuevo;
• cambiar usage y coste sin un límite visible;
• impedir que el client sepa a qué intento pertenece cada evento.

Si un stream se rompe después de empezar, devuelve un error Partial o de transporte con el Request ID original. La aplicación puede ofrecer “reintentar”, continuar desde un checkpoint seguro o descartar el resultado parcial. No debe unir un stream nuevo al anterior como si fueran una sola respuesta.

Para Function Calling, persiste los Tool Call IDs aceptados y sus efectos antes de que un retry pueda recrearlos. La comparación de Function Calling explica cómo combinar Call IDs e idempotencia de aplicación.

Acotar backoff por intentos y tiempo total

Exponential Backoff separa los intentos en el tiempo; Jitter 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 deadline. El backoff no autoriza el retry: antes deben pasar los gates de fallo e idempotencia.

Define un budget total, no solo un contador:

• máximo de intentos por acción;
• tiempo total, incluyendo queue y backoff;
• intentos antes y después de seleccionar un fallback group;
• tiempo mínimo restante para producir una respuesta útil;
• propagación de cancelación a todos los intentos activos.

En una petición interactiva con deadline de 15 segundos, tres intentos de 10 segundos no forman una política real. Un job batch puede tener más margen, pero también necesita deadline terminal y Durable Job ID.

Evitar Retry Amplification entre capas

Si el SDK ejecuta tres intentos, el gateway prueba tres rutas por cada uno y el proxy upstream hace dos llamadas por ruta:

3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls

Una acción del usuario se convierte en 18 llamadas. Durante un incidente aumenta colas, rate limits, coste y tiempo de recuperación.

Asigna la propiedad del retry:

• el gateway gestiona el same-contract channel failover inmediato;
• la aplicación decide si puede repetirse la acción completa;
• los retries automáticos del SDK se desactivan o acotan cuando el gateway ya reintenta;
• los jobs asíncronos usan un Durable Job ID y un Attempt Ledger;
• ninguna capa inicia un intento tras cancelar el caller.

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

Verificar que el fallback conserva el contrato

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

Área	Evidencia necesaria
Model Identity	El modelo solicitado existe sin Silent Mapping
Endpoint	La request de Responses o Chat Completions se acepta como está configurada
Streaming	Event Types, finalización, usage y cancelación funcionan
Structured Output	El subconjunto necesario de JSON Schema y strict behavior funciona
Function Calling	Tools, Call IDs, argumentos streaming y resultados hacen Round-trip
Limits	Context, output, rate y concurrency encajan con el workload
Errors	Status y error bodies se pueden clasificar sin filtrar Secrets
Usage and Cost	Tokens, cache fields, Service Tier y política de precio están definidos
Safety and Region	Policy, Data Path y requisitos de residencia siguen cumpliéndose

Si una ruta falla en un requisito obligatorio, no es un fallback transparente para ese workload. Puede usarse bajo otra política explícita.

Cambiar de modelo siempre requiere una decisión de producto: modelo permitido, Quality Floor, Price Ceiling, Tool Contract y comunicación al usuario. No cambies silenciosamente a un modelo más barato o débil por un error de ruta.

Entender el fallback actual de Modelflare

Modelflare busca rutas elegibles para el modelo solicitado. Una API Key normal tiene un Primary Group y puede tener una lista ordenada de Fallback Groups. Una Smart API Key evalúa los grupos disponibles según su Routing Strategy. Ninguno debe sustituir silenciosamente el modelo.

El Group-level RPM Admission ocurre antes de facturación y de la llamada upstream. Si el grupo está lleno, se evalúa otro grupo ordenado o candidato de Smart Routing; sin grupos elegibles, se responde 429.

Dentro del grupo, Channel Priority marca el orden de Account Failover. Tras un error upstream, el canal se excluye y la selección continúa. El failover actual no depende de RetryTimes ni AutomaticRetryStatusCodes; termina con éxito, agotamiento de rutas, cancelación o cuando ya comenzó el output y no puede repetirse de forma transparente.

Estas decisiones internas de ruta para el mismo modelo no autorizan al client a añadir un loop ilimitado. Consulta Reliable AI API Routing para diseñar grupos y canales, y AI API Error Troubleshooting para separar errores de policy y fallos upstream.

Conservar evidencia de cada intento

Un 200 final no prueba que la primera ruta funcionara. Un Channel ID final tampoco describe los intentos fallidos. Conserva como mínimo:

• Request ID estable y Correlation ID visible para el caller;
• secuencia de intentos y referencias de grupo/canal;
• modelo y contrato de endpoint de cada intento;
• Status, Error Class y Stream Phase;
• si el output downstream había comenzado;
• hitos de timing y estado de cancelación;
• Input, Output y Cached-token Usage cuando estén disponibles;
• coste de cada intento completado o facturable;
• razón terminal: Success, Exhausted, Cancelled, Partial o Policy Stop.

No almacenes API Keys, Raw Prompts, Raw Responses ni credenciales solo para investigar fallback. Normalmente bastan clases de error redactadas y timing; reserva archivos de request breves y restringidos para investigaciones habilitadas de forma explícita.

Ensayar la política antes de producción

Ejecuta el protocolo real con inputs seguros y deterministas:

1. deshabilita el canal primario antes de headers y verifica la siguiente ruta same-model;
2. devuelve rate limit y comprueba límites y Retry-After;
3. cancela el caller y prueba que no empieza otro intento;
4. rompe el stream tras producir output y prueba que no hay replay transparente;
5. envía una request inválida y confirma que fallback no la oculta;
6. repite un Tool Workflow y confirma un solo efecto externo;
7. agota todas las rutas y verifica un único error terminal;
8. revisa el Attempt Ledger y reconcilia usage y coste.

Despliega primero en un workload pequeño. Mide por separado Attempt Count, Success-after-fallback y Raw Success Rate, y conserva una forma rápida de retirar rutas no saludables. El objetivo no es maximizar fallbacks, sino recuperar de forma segura, dentro del deadline, preservando el modelo y dejando evidencia de cada intento.