Un circuit breaker de gateway API de LLM evita que una aplicación siga enviando tráfico repetidamente a una ruta que ya está fallando. Sin esa protección, un tiempo de espera puede provocar reintentos, los reintentos pueden provocar intentos de fallback, los intentos de fallback pueden generar más errores del proveedor, y la aplicación puede convertir un único incidente upstream en un bucle de fallo del proveedor.
El objetivo no es sustituir los reintentos ni el fallback del modelo. El objetivo es decidir cuándo una ruta está lo bastante degradada como para que el gateway deje de intentarla durante una breve ventana, envíe una sonda controlada más tarde y elija un resultado más seguro mientras el breaker está abierto: fallback, cola, degradación o fallo cerrado.
Flatkey es relevante porque flatkey.ai posiciona públicamente el producto en torno a una sola clave de API, una URL base compatible con OpenAI en https://router.flatkey.ai/v1, enrutamiento, facturación unificada, analíticas de uso, controles del panel, conmutación automática, balanceo de carga y límites de cuota. Esos son puntos centrales útiles para el trabajo de fiabilidad. No eliminan la necesidad de definir una política clara de circuit breaker de gateway API de LLM para los flujos de trabajo de su propia aplicación.
Respuesta rápida: Qué debe hacer un interruptor automático de la API gateway de un LLM
Un interruptor automático de la API gateway de un LLM práctico tiene tres estados de ruta y una ruta de cierre por defecto. Mantenga la política lo bastante simple como para que los ingenieros de guardia puedan explicarla durante un incidente.
| Estado | Comportamiento de la gateway | Qué lo cambia | Evidencia que registrar |
|---|---|---|---|
| Cerrado | El tráfico puede usar el proveedor, el modelo, la familia de endpoints, la cuenta o el grupo de rutas. | La tasa de error, la tasa de timeouts, la latencia, las respuestas de sobrecarga o las comprobaciones de salud fallidas superan el umbral. | ID de la política de ruta, modelo seleccionado, proveedor, familia de endpoints, latencia, código de estado, recuento de reintentos y coste. |
| Abierto | La gateway deja de enviar tráfico normal a la ruta no saludable durante una ventana de enfriamiento. | Expira el enfriamiento, o un operador permite manualmente una prueba. | Motivo del interruptor, hora de apertura, recuento de intentos bloqueados, ruta de fallback, decisión de cola o motivo de cierre por defecto. |
| Medio abierto | La gateway permite un número limitado de solicitudes de prueba antes de restaurar el tráfico. | Las pruebas exitosas cierran el interruptor; las pruebas fallidas lo vuelven a abrir. | Tamaño de la muestra de prueba, flujo de trabajo de prueba, resultado de la prueba, latencia, uso y aprobación del propietario de la ruta. |
| Cierre por defecto | La gateway se niega a enrutar la solicitud porque el problema no es de salud del proveedor. | Riesgo de autenticación, política, cuota, seguridad, límite de datos, solicitud inválida o efecto secundario de una herramienta. | Motivo de la detención, propietario, mensaje visible para el usuario y ruta de remediación. |
Por qué los reintentos crean bucles de fallo del proveedor
Los reintentos son útiles cuando una solicitud falla por un motivo transitorio. Se vuelven peligrosos cuando cada solicitud del usuario crea varias llamadas ascendentes más, especialmente durante una interrupción del proveedor o una ventana de sobrecarga. Un bucle de reintentos puede consumir límites de velocidad, gastar cuota, aumentar la latencia y ocultar el fallo original detrás de un error final.
Un disyuntor cambia la pregunta sobre los reintentos. En lugar de preguntar: "¿Debería esta solicitud reintentarse otra vez?", la puerta de enlace pregunta: "¿Está esta ruta lo suficientemente sana como para recibir más tráfico ahora mismo?" Esa visión a nivel de ruta importa para las cargas de trabajo de LLM porque cada solicitud puede ser costosa, de larga duración, de transmisión continua, usar herramientas y ser visible para el cliente.
El patrón de diseño en la nube de Microsoft para disyuntores describe la misma idea central para servicios remotos: después de fallos repetidos, el circuito se abre para que la aplicación no siga intentando una operación que probablemente falle. Para una ruta de IA, el mismo patrón necesita límites específicos de LLM: comportamiento del modelo, familia de endpoint, gasto de tokens, estado de transmisión, efectos secundarios de herramientas, clase de datos y aprobación de fallback.
Clasifica los errores antes de que lleguen al breaker
La forma más rápida de construir un mal AI API circuit breaker es contar cada fallo como salud del proveedor. Eso crea falsos positivos. También puede ocultar problemas que el propietario de la aplicación debe corregir.
| Error Or Event | Breaker Decision | Reason | Default Outcome |
|---|---|---|---|
| Provider 500, 503, overload, unavailable, connection failure, repeated upstream timeout | Count toward route health. | These are plausible provider, route, capacity, or network-health signals. | Retry within a tight budget, then open the route breaker if thresholds are crossed. |
| 429 request-rate limit | Classify carefully. | A provider-wide overload signal and an app-created burst need different handling. | Throttle, back off, or open only the scoped route that is actually saturated. |
| 429 monthly quota, exhausted credits, or spend limit | Do not count as provider health. | This is a budget or account-owner condition. | Fail closed, alert the budget owner, or route only if a pre-approved budget exists. |
| 401 auth, incorrect key, organization membership, IP allowlist, unsupported region | Do not count as provider health. | The request is not allowed to use the route. | Fail closed and fix credentials, account, IP, or region policy. |
| Invalid request, unsupported parameter, unsupported model, malformed schema | Do not count as provider health. | The app sent a request shape the route cannot serve. | Fix the request or choose a compatible model before routing. |
| Safety, moderation, DLP, compliance, or unapproved data-class block | Never bypass with fallback. | Routing to another model could cross a policy boundary. | Fail closed and record the policy decision. |
| Tool already executed, partial stream already shown, user cancelled request | Do not silently replay. | The app may create duplicate side effects or merge two model outputs. | Mark incomplete, require explicit user retry, or use an idempotent recovery path. |
La guía de códigos de error de OpenAI es un ejemplo útil de por qué importa esta taxonomía: separa los problemas de autenticación y lista de अनुमति IP, los problemas de región no compatible, los límites de tasa, el agotamiento de cuota, los errores del servidor, la sobrecarga y las desaceleraciones repentinas de la tasa de solicitudes. La documentación de Anthropic y Google Gemini hace distinciones similares entre límites de tasa, condiciones de sobrecarga/no disponible, solicitudes no válidas y problemas de permiso o cuota. Tu LLM API gateway circuit breaker debería mantener separadas esas clases antes de abrir una ruta.
Scope el breaker al tramo más pequeño que explique la falla
Un breaker demasiado amplio causa tiempo de inactividad innecesario. Un breaker demasiado estrecho permite que el mismo bucle de fallo del proveedor continúe a través de rutas cercanas. Delimita el breaker a la dimensión de ruta más pequeña que explique el incidente.
| Ámbito | Cuándo usarlo | Riesgo si se delimita mal |
|---|---|---|
| Proveedor | Varios modelos del mismo proveedor no están disponibles o están sobrecargados. | Demasiado amplio si solo falla un modelo, una cuenta o una familia de endpoints. |
| Modelo | Una familia de modelos tiene errores repetidos de 5xx, timeout o de ruta no compatible. | Demasiado estrecho si la cuenta upstream o el proveedor están saturados. |
| Familia de endpoints | Chat funciona, pero Responses, image, video, Anthropic Messages o las rutas de Gemini se comportan de forma diferente. | Mezclar familias de endpoints puede ocultar fallos específicos del protocolo. |
| Cuenta, grupo, región o ruta del proveedor | Solo falla una cuenta upstream, grupo de enrutamiento, región o ruta del proveedor. | No aislar el fallo puede consumir capacidad saludable en otro lugar. |
| Flujo de trabajo | Las llamadas a herramientas, el streaming, los trabajos por lotes o el chat orientado al cliente tienen distintas reglas de seguridad y repetición. | Una ruta segura para enriquecimiento por lotes puede no ser segura para flujos en vivo de usuarios. |
Para los usuarios de Flatkey, esto significa que debes probar desde el flujo de trabajo y la ruta que realmente planeas usar. La instantánea actual de la API de precios de Flatkey para este artículo devolvió 638 filas de modelos, 23 proveedores y familias de endpoints para OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, generación de imágenes y video de OpenAI. Tómalo como evidencia fechada del 18 de junio de 2026, no como un contrato permanente de rutas.
Establece umbrales que coincidan con el tráfico de LLM
Un circuit breaker de gateway API de LLM no debería abrirse por un fallo aislado. Tampoco debería esperar hasta que falle cada solicitud de cliente. Usa umbrales que combinen volumen mínimo de tráfico, ratio de fallos, latencia y enfriamiento.
| Umbral | Punto de partida práctico | Por qué importa |
|---|---|---|
| Tamaño mínimo de muestra | Abrir solo después de que se hayan observado suficientes solicitudes o sondas. | Evita que una sola finalización costosa abra una ruta global. |
| Ratio de fallos | Seguimiento de los fallos recuperables del upstream por separado de los fallos propios de la aplicación. | Evita que los errores de autenticación, cuota y solicitudes malformadas contaminen la salud de la ruta. |
| Umbral de latencia o tiempo de espera | Usa presupuestos de tiempo de espera específicos por endpoint para las rutas de chat, streaming, imagen y video. | Un buen umbral para chat puede ser incorrecto para video o generación por lotes. |
| Enfriamiento de apertura | Mantén la ruta abierta el tiempo suficiente para detener tormentas de reintentos y luego realiza una sonda. | Protege tanto al proveedor como a tu propia cola de solicitudes. |
| Límite de sondas en medio abierto | Permite un número pequeño y controlado de solicitudes de prueba antes de cerrar. | Evita un aumento total del tráfico cuando un proveedor solo se ha recuperado parcialmente. |
| Techo de coste | Establece un gasto máximo estimado para reintentos, fallback y sondas. | Evita que la recuperación de la fiabilidad se convierta en un incidente de facturación. |
Los límites de tasa forman parte de la discusión sobre umbrales. La guía de límites de tasa de OpenAI explica que los límites de tasa protegen contra el abuso, garantizan un acceso justo y ayudan a gestionar la carga agregada. Si tu aplicación sigue reintentando hacia una ruta con límite de tasa, tu propio patrón de tráfico puede convertirse en el incidente. El circuit breaker de gateway API de LLM debería funcionar junto con la regulación del lado del cliente, la cola y los controles de cuota, no ir en contra de ellos.
Decide qué sucede mientras el breaker está abierto
Abrir un breaker solo es útil si la gateway tiene una siguiente acción definida. No permita que cada ruta abierta recurra automáticamente a cualquier modelo disponible.
| Acción en estado abierto | Cuándo usar | Guardrail requerido |
|---|---|---|
| Ruta de fallback | El modelo o proveedor de respaldo ya está aprobado para el flujo de trabajo. | Ejecute las mismas comprobaciones de evaluación, esquema, herramienta, límite de datos y costo antes de producción. |
| Encolar | El trabajo es asíncrono o la experiencia del usuario puede tolerar la demora. | Conserve los metadatos de propietario, cliente, modelo, costo y reintento. |
| Degradar | Se acepta un resultado parcial de menor riesgo, como una respuesta en caché o una funcionalidad reducida. | Haga visible el estado degradado para la app y los registros. |
| Fallar cerrado | La solicitud presenta riesgo de política, presupuesto, seguridad, autenticación, región o efectos secundarios. | Devuelva un error claro y alerte al propietario adecuado en lugar de intentar con otro modelo. |
La documentación pública de Vercel AI Gateway describe los fallbacks de modelos como un patrón de gateway con modelos de respaldo ordenados. Úselo solo como evidencia de categoría. En su propia pila, el fallback es una decisión de aprobación separada. El breaker decide si una ruta está sana en este momento; el fallback decide si otra ruta puede servir la misma solicitud.
Streaming y las llamadas a herramientas necesitan paradas adicionales
La transmisión facilita ocultar un bucle de fallos del proveedor. Si la aplicación reinicia silenciosamente una solicitud después de una salida parcial, un usuario puede ver una respuesta combinada de dos intentos. Las llamadas a herramientas añaden un segundo problema: un reintento o un fallback puede duplicar un reembolso, una actualización de ticket, un correo electrónico, una escritura en base de datos o una acción externa.
Use estas reglas en la política de circuit breaker de la pasarela de API LLM:
- Antes de la primera salida: se puede permitir un reintento o fallback si la ruta está aprobada y el breaker está cerrado o en estado half-open.
- Después de la primera salida: marque la transmisión como incompleta y exija un reintento explícito del usuario en lugar de un fallback silencioso.
- Después de la ejecución de la herramienta: no repita la acción a menos que la herramienta sea idempotente y la operación tenga una clave de reproducción.
- Después de un bloqueo por política: falle en cerrado. No enrute a un modelo diferente para eludir el bloqueo.
Esto se combina con las guías estrategia de reintento de API de IA, lista de verificación de fallback de modelos y balanceo de carga y failover de API de IA. El breaker debe compartir la misma taxonomía de fallos que esos playbooks.
Campos de observabilidad para la revisión del circuit breaker
Si una solicitud tiene éxito solo porque el gateway omitió silenciosamente una ruta rota, el incidente sigue necesitando visibilidad. La documentación de AI Gateway de Cloudflare ofrece un ejemplo público de patrones de observabilidad de gateways de IA: los registros de solicitudes pueden incluir proveedor, estado, tokens, coste y duración, y los metadatos personalizados pueden etiquetar solicitudes para filtrarlas posteriormente. Los registros de tu gateway deberían ofrecer el mismo nivel de evidencia de ruta para las decisiones del breaker.
| Field | Why Operators Need It |
|---|---|
| Breaker policy ID and version | Shows which rule opened, closed, or bypassed the route. |
| Breaker state at decision time | Explains whether the route was closed, open, half-open, or fail-closed. |
| Requested model, selected model, provider, account, group, and endpoint family | Separates user intent from the gateway route decision. |
| Error class per attempt | Distinguishes upstream failures from auth, quota, invalid request, policy, and tool errors. |
| Latency, timeout, retry count, and probe result | Shows whether the route failed slowly, failed quickly, or recovered during half-open probing. |
| Partial-output flag and tool side-effect status | Prevents hidden mixed-output or duplicate-action incidents. |
| Usage, cost, quota owner, and final disposition | Connects reliability recovery to spend, budgets, and accountability. |
El artículo complementario AI API observability logs profundiza en el registro de incidentes. Para los circuit breakers, prioriza el estado de la ruta y la razón exacta por la que una solicitud fue bloqueada, sondeada, enrutada, en cola o falló cerrada.
Plan de implementación de Flatkey para políticas de circuit breaker
Utiliza este enfoque por etapas antes de confiar en un circuit breaker de gateway API de LLM para el tráfico de clientes a través de Flatkey o de cualquier gateway compatible con OpenAI.
- Crear una clave de staging: mantiene las pruebas del breaker separadas del tráfico de producción de clientes.
- Confirmar la ruta base: apunta un cliente compatible con OpenAI a
https://router.flatkey.ai/v1y verifica el modelo, la familia de endpoint, la fila de uso y la visibilidad en el panel. - Tomar una instantánea del catálogo de rutas: guarda la página de precios de Flatkey y la respuesta de la API de precios en la fecha de implementación para que las suposiciones sobre rutas y precios sean auditables.
- Definir la taxonomía de errores: decide qué errores cuentan para la salud de la ruta y cuáles fallan cerrado antes de que el breaker los vea.
- Comenzar con un flujo de trabajo: aplica el breaker a una ruta de modelo, una familia de endpoint y una clase de tráfico antes de ampliar.
- Forzar pruebas de fallo: simula timeout del proveedor, 500, 503, 429 por tasa de solicitudes, agotamiento de cuota, fallo de autenticación, solicitud malformada, stream parcial y efecto secundario de herramienta.
- Verificar el comportamiento en estado abierto: confirma que las acciones de fallback, cola, degradación o fallo cerrado coinciden con la matriz de aprobación.
- Revisar logs y facturación: confirma que el estado del breaker, la ruta seleccionada, el uso, el coste y el propietario de la cuota sean visibles después de cada prueba.
- Establecer la reversión: desactiva la política si se abre de forma demasiado amplia, oculta errores pertenecientes a la app o genera un gasto inesperado.
Plantilla de política de disyuntor
Esta plantilla no es un contrato de API de Flatkey. Trátela como un artefacto de revisión para los responsables de ingeniería, producto, finanzas y seguridad.
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}Preguntas frecuentes
¿Qué es un circuit breaker de gateway API de LLM?
Un circuit breaker de gateway API de LLM es una política de salud de ruta que impide que el tráfico normal llegue a un modelo, proveedor, cuenta o familia de endpoints no saludables después de fallos repetibles y recuperables. Se abre durante una ventana de enfriamiento, permite sondeos limitados en estado half-open y se cierra solo después de que la ruta vuelva a parecer saludable.
¿Qué errores de la API de LLM deberían abrir un circuit breaker?
Los errores 5xx del lado del proveedor, la sobrecarga, las respuestas no disponibles, los fallos de conexión y los timeouts ascendentes repetidos suelen ser candidatos típicos. Los errores de autenticación, los fallos de allowlist de IP, las regiones no compatibles, la cuota agotada, las solicitudes mal formadas, los bloqueos por políticas y los efectos secundarios de herramientas normalmente deberían fallar de forma cerrada en lugar de abrir un breaker de salud del proveedor.
¿En qué se diferencia un circuit breaker de un retry o un fallback?
Retry decide si una solicitud debe intentarse de nuevo. Fallback decide si otra ruta aprobada puede atender la solicitud. Un circuit breaker decide si una ruta debe recibir tráfico normal en absoluto mientras parece no saludable.
¿Deberían aplicarse los circuit breakers a respuestas de streaming de LLM?
Sí, pero con límites más estrictos. Un breaker puede proteger la ruta antes del primer token visible. Después de una salida parcial o de un efecto secundario de una herramienta, la aplicación no debería reproducir silenciosamente ni hacer fallback, a menos que el flujo de trabajo esté diseñado explícitamente para una recuperación idempotente.
Revisión final antes de habilitar el interruptor
Antes de habilitar un cortacircuitos de gateway de API de LLM, haga una pregunta: si esta ruta se abre durante un incidente del proveedor, ¿puede el equipo explicar qué falló, por qué se detuvo el tráfico normal, a dónde fue el tráfico después, cuánto costó y cómo cerrar o revertir la política?
Si la respuesta es no, mantenga el interruptor en staging. Si la respuesta es sí, use el acceso centralizado a modelos de Flatkey, el enrutamiento, la visibilidad de uso, la facturación y los controles de cuota como parte del ciclo de revisión. Cuando esté listo para validar rutas detrás de un solo gateway compatible con OpenAI, obtenga una clave y empiece con un flujo de trabajo, una ruta de modelo y una política de cortacircuitos.
