429, 5xx y timeouts: prácticas de ingeniería para la tolerancia a fallos en gateways LLM

Primero clasificar, luego decidir cómo actuar

'Reintentar tres veces todos los errores' es la práctica errónea más común. La semántica de cada código de error es completamente distinta y la estrategia de tratamiento también debe serlo. La siguiente tabla es la estrategia que aplica realmente nuestro gateway y puede servir de referencia para tu propia implementación.

• Fallo de conexión / DNS / TLS: cambiar de inmediato al canal de respaldo.
• Timeout (aún sin empezar a emitir): cambiar al canal de respaldo, como máximo 1~2 veces.
• HTTP 429: tras un enfriamiento breve, cambiar de canal y a la vez reducir el peso de ese canal.
• HTTP 5xx: contar en la ventana de fallos; los fallos consecutivos disparan el cortacircuitos.
• 401 / 403: problema de credenciales o permisos; deshabilitar esa credencial y alertar, no reintentar.
• Saldo insuficiente: pausar ese canal y alertar.
• Error de parámetros 400: tras normalizar, devolver directamente al cliente, sin reintentar ni facturar.
• SSE interrumpido tras emitir parte del contenido: devolver upstream_stream_error, sin reintentar por defecto.

Por qué una interrupción SSE no se puede reintentar sin más

Una vez que la respuesta en streaming ha empezado a emitir tokens al cliente, significa que el proveedor ya ha generado una salida (y la va a facturar). Si en ese momento el gateway cambia silenciosamente a otro canal y lo repite, el usuario verá contenido duplicado y tú pagarás por dos salidas.

Lo correcto es tratar ese flujo a medias como un éxito parcial: devolver un código de error que indique al cliente 'interrupción del proveedor', y que el lado del negocio decida si muestra el contenido ya recibido con un aviso de reintento o si lo repite todo desde el principio.

Cortacircuitos: la capa más importante que el reintento

El reintento es el tratamiento de una petición individual; el cortacircuitos es el juicio sobre el estado global durante un periodo. Cuando un canal acumula fallos consecutivos hasta el umbral, se marca directamente como 'abierto', se deja de enviarle tráfico durante un tiempo y luego se le envía una pequeña cantidad de tráfico de sondeo (semiableirto); tras varios sondeos exitosos se recupera por completo (cerrado).

Sin cortacircuitos, los reintentos presionan aún más un canal ya caído y disparan la latencia media del cliente.

Idempotencia y facturación de los reintentos

• Peticiones no streaming: tras un reintento solo se factura el usage de la última vez que tuvo éxito.
• Peticiones streaming: la vez que ya emitió tokens genera un coste real en el proveedor y debe registrarse; no se puede cuadrar la cuenta porque haya habido un reintento.
• Asignar un request_id a cada petición del usuario, compartido por todos los reintentos, para poder reproducir después por qué se fue por ese canal.
• Los reembolsos/ajustes deben pasar por el libro mayor, no se puede modificar el saldo directamente.

Lo que Admesh ya hace

Esta estrategia es el comportamiento por defecto en el gateway de Admesh: conmutación automática entre varios canales del mismo public_model, cada decisión de enrutamiento se persiste en base de datos y el cliente puede ver en el registro de uso el request_id, el modelo realmente utilizado y el estado de salud del canal; los códigos de error se devuelven en formato unificado (error.type / error.code / request_id).

Cabe destacar que el enrutamiento solo ocurre dentro del pool de canales del mismo public_model; no te cambiamos a un modelo de otro proveedor porque pidas anthropic/xxx — sustituir entre modelos cambia directamente la calidad de la salida, y esa es una decisión que no podemos tomar por ti.

Ver referencia rápida de códigos de error →