Errores comunes de LiteLLM: tiempos de espera, alertas de presupuesto y fallos de proveedores

Errores comunes de LiteLLM: tiempos de espera, alertas de presupuesto y fallos de proveedores

La mayoría de los errores comunes de LiteLLM parecen inicialmente un problema del proveedor: una solicitud agota el tiempo de espera, una alerta de presupuesto nunca llega o un modelo que funciona correctamente devuelve de repente un 404 o un 503. La solución más rápida es identificar la capa de control que falla antes de cambiar los reintentos o sustituir modelos.

Utilice esta guía para distinguir entre los plazos del cliente, la política de la puerta de enlace LiteLLM, la configuración del modelo, la capacidad del proveedor y la aplicación del gasto. Incluye un pequeño flujo de trabajo para incidentes que puede repetir para tiempos de espera, controles de presupuesto y fallos de proveedores.

Respuesta rápida: Conserve una solicitud fallida, clasifique el error, reprodúzcalo con una llamada mínima y cambie un control a la vez. Comience con el tipo de excepción normalizado de LiteLLM, los metadatos de la solicitud y el ID de llamada, no solo con el estado HTTP.

LiteLLM asigna muchos fallos de proveedores a tipos de excepción compatibles con OpenAI y expone el estado HTTP, el mensaje y el proveedor de origen en la excepción. Esto facilita la resolución de los errores comunes de LiteLLM cuando mantiene intacto el contexto del error original en lugar de reemplazarlo por un 500 genérico. Consulte la referencia de asignación de excepciones de LiteLLM para ver la asignación actual.

La matriz de errores comunes de LiteLLM

Esta tabla es el principal recurso de valor de esta guía de errores comunes de LiteLLM: convierte un fallo impreciso de la puerta de enlace en la siguiente observación específica.

Un flujo de triaje de errores comunes de LiteLLM en cinco minutos

Antes de editar config.yaml, guarde un fallo representativo. Oculte los secretos y el contenido del prompt cuando sea necesario, pero conserve los campos operativos.

1. Capture la identidad de la solicitud. Registre la marca de tiempo, el entorno, la ruta, el model solicitado, el estado HTTP, el tipo de excepción de LiteLLM, el mensaje de error, el nombre del proveedor y el número de intento del cliente.
2. Capture la identidad de la puerta de enlace. Guarde x-litellm-call-id cuando esté presente. LiteLLM documenta esta cabecera como el mejor identificador para seguir una solicitud a través de los sistemas de registro. Registre también x-litellm-model-id, x-litellm-model-api-base y las cabeceras de versión si su respuesta las expone. La documentación de registro de LiteLLM enumera las cabeceras actuales.
3. Clasifique el fallo. ¿Se trata de una solicitud no válida, un problema de autenticación/permisos, un límite de presupuesto/tasa, un tiempo de espera o un fallo del servicio ascendente? No coloque todos los errores 4xx en un único grupo de reintentos.
4. Haga una reproducción mínima fuera de producción. Use la misma clave virtual y el model_name público que utiliza la aplicación. Elimine la concurrencia específica de la aplicación y las llamadas a herramientas antes de probar una solicitud básica.
5. Cambie solo una capa. Una corrección de nombre de modelo, un cambio de tiempo de espera y un cambio de fallback en la misma implementación hacen imposible explicar el resultado final.

Aquí tiene una prueba mínima genérica para un proxy LiteLLM compatible con OpenAI:

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

La cuestión no es que support-chat sea un nombre de modelo universal. La cuestión es que la prueba debe usar el nombre público configurado en su gateway y luego conservar los encabezados y el cuerpo de la respuesta para compararlos con la solicitud fallida de la aplicación.

Errores de tiempo de espera: encuentre el plazo que realmente se activó

Los tiempos de espera están entre los errores comunes de LiteLLM más engañosos porque una solicitud puede expirar en más de una capa:

• El llamador puede cancelar primero.
• La implementación o el enrutador de LiteLLM pueden aplicar un plazo más corto.
• El request_timeout del proxy puede detener una llamada ascendente de larga duración.
• El proveedor, el balanceador de carga o la ruta de red pueden cerrar la solicitud.
• Una respuesta transmitida puede comenzar correctamente y luego bloquearse entre fragmentos.

El mapeo de excepciones de LiteLLM documenta los fallos de tiempo de espera como openai.APITimeoutError. Para rutas nativas y de paso directo, la documentación actual sobre tiempos de espera describe un orden de precedencia entre la configuración de solicitud, implementación, enrutador y proxy. Compruebe la versión de la documentación que coincide con su implementación antes de aplicar un cambio de configuración.

Comience con un presupuesto de plazo, no con un número mayor

Elija la latencia total que puede tolerar su flujo de usuario y luego asígnela hacia atrás. Por ejemplo, una experiencia interactiva podría reservar tiempo para la espera en cola, un reintento y el renderizado de la respuesta, en lugar de permitir que la llamada ascendente consuma todo el plazo visible para el usuario.

# Punto de partida ilustrativo — ajústelo a su carga de trabajo y versión de LiteLLM.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

El ejemplo es intencionadamente conservador: proporciona al proxy un modo de fallo acotado en lugar de dejar que las conexiones queden bloqueadas. La guía de producción de LiteLLM recomienda establecer un tiempo de espera de solicitud y usar registros estructurados de producción.

Cuando se produzca un tiempo de espera, responda estas preguntas en orden:

No permita que un reintento automático por tiempo de espera continúe indefinidamente. Un reintento es razonable solo cuando el trabajo se puede repetir de forma segura y un intento alternativo aún puede terminar dentro del plazo del llamador. Si una solicitud activa herramientas, escribe datos o inicia una transmisión visible para el usuario, defina primero la idempotencia y la semántica de reinicio.

Para problemas de espera en cola o capacidad impulsados por 429 que se manifiestan como latencia prolongada, complemente esta sección con la guía de RPM, TPM y reintentos de Flatkey. Un tiempo de espera puede ser el síntoma de un control de admisión sobrecargado, no de una configuración de duración de la solicitud.

Alertas de presupuesto: separe la notificación de la aplicación

El comportamiento de los presupuestos provoca una proporción desmedida de los errores comunes de LiteLLM porque los equipos a menudo agrupan tres controles diferentes bajo la palabra «alerta». No son intercambiables.

La primera comprobación del presupuesto: ¿hay una base de datos?

La documentación actual sobre presupuestos de LiteLLM es explícita: los presupuestos de su proxy se aplican al gasto leído desde la base de datos. En una implementación sin base de datos, un max_budget global configurado no actúa como un límite de gasto fiable; el comportamiento de los presupuestos de claves virtuales, equipos y usuarios también depende de la base de datos.

Esto conduce a un patrón de fallo común: un equipo establece max_budget, ve una advertencia de inicio o un valor de configuración y asume que el tráfico de producción se detendrá en el umbral. No será un control fiable sin la configuración necesaria de seguimiento del gasto.

# Illustrative policy only. Validate with a non-production key before rollout.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

Trate fail_closed_budget_enforcement como una decisión de fiabilidad, no como una solución para copiar y pegar. La documentación actual de LiteLLM explica que una comprobación de presupuesto más estricta puede rechazar solicitudes cuando no se puede verificar el gasto; pruebe el comportamiento ante fallos de la base de datos y de Redis en su implementación antes de activarla de forma generalizada.

Pruebe la ruta del presupuesto, no solo el panel

Utilice una clave o equipo desechable en un entorno que no sea de producción y verifique esta secuencia:

1. Confirme que el proxy puede leer y escribir en el almacén de gasto.
2. Cree un presupuesto rígido deliberadamente pequeño en el ámbito correcto: clave, equipo, usuario, proyecto o usuario final.
3. Envíe una solicitud mínima a través del proxy.
4. Envíe una segunda solicitud que deba superar el umbral.
5. Compruebe de forma independiente la excepción devuelta, el registro de gasto, la ventana de restablecimiento y el canal de alertas.
6. Confirme que la aplicación gestiona un bloqueo de presupuesto sin reintentarlo como si fuera una sobrecarga transitoria del proveedor.

LiteLLM también documenta las ventanas presupuestarias y los controles de presupuesto por modelo. Sea preciso con el calendario de restablecimiento: una barrera de protección diaria y un límite mensual resuelven riesgos distintos.

Las alertas de presupuesto de Azure y las alertas de presupuesto de AWS son medidas de respaldo, no sustitutos

Las palabras clave secundarias alertas de presupuesto de Azure y alertas de presupuesto de AWS son importantes porque las alertas de facturación de los proveedores de nube cubren un límite diferente. Pueden advertir sobre el gasto de una cuenta o suscripción del proveedor, incluido el tráfico que omite LiteLLM. No sustituyen una decisión a nivel de gateway sobre si esta solicitud, clave, inquilino o modelo debe admitirse ahora.

Utilice ambas capas cuando corresponda:

• La política de presupuesto de LiteLLM protege la ruta y el inquilino que el gateway puede identificar.
• Las alertas de presupuesto de Azure o las alertas de presupuesto de AWS supervisan el gasto de la cuenta de nube ascendente.
• Un libro mayor de uso del gateway reconcilia ambas y expone el tráfico que omitió la ruta prevista.

Para el gasto de OpenAI, la comprobación de tasa de captura de gasto de LiteLLM puede comparar el gasto registrado con la API de costes de la organización de OpenAI. Actualmente tiene requisitos previos específicos del proveedor, así que lea la documentación versionada antes de tratarla como una función universal de conciliación multiproveedor.

Si la necesidad operativa es más amplia que una única implementación de LiteLLM, consulte la guía de evaluación de paneles unificados de facturación de IA para conocer las preguntas que debe plantearse sobre claves, presupuestos, asignaciones, alertas y conciliación.

Fallos de proveedores: verifique por separado el nombre público del modelo y la implementación ascendente

Los fallos de proveedores son los errores comunes de LiteLLM más visibles, pero a menudo son errores de configuración del gateway. Normalmente, un cliente llama al model_name público que usted expone. Luego, LiteLLM resuelve ese nombre en un modelo de proveedor, implementación, endpoint, credencial y parámetros específicos del proveedor.

model_list:
  - model_name: support-chat       # The name the client requests
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

El model_name y litellm_params.model son conceptos deliberadamente distintos. Cuando un cliente recibe un error de modelo no válido, compare primero el nombre exacto solicitado con model_name. La documentación de gestión de modelos de LiteLLM distingue el nombre público del modelo del modelo del proveedor y ofrece un flujo de trabajo de prueba de conexión para los modelos configurados.

Tabla de decisiones para fallos de proveedores

El tipo de excepción debe determinar la siguiente acción. La referencia de excepciones de LiteLLM asigna las condiciones 401, 402, 403, 404, 408, 429, 500 y 503 a clases normalizadas; también expone campos específicos del proveedor para una investigación más profunda.

Reintentos, alternativas y periodos de enfriamiento: recupérese sin ocultar el incidente

Los reintentos y las alternativas pueden reducir los fallos visibles, pero también pueden convertir un error de configuración en latencia, coste o trabajo duplicado. Una buena gestión de los errores comunes de LiteLLM utiliza una política distinta para una configuración no válida que para una breve interrupción del proveedor.

LiteLLM documenta una división útil:

• Los reintentos intentan recuperarse dentro del grupo de modelos actual.
• Las alternativas pasan a otro grupo de modelos después de los reintentos configurados.
• Los periodos de enfriamiento aíslan una implementación que está fallando mientras las alternativas en buen estado siguen disponibles.

Aquí tiene una pequeña configuración ilustrativa basada en la guía de conmutación por error de proveedores de LiteLLM:

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

Valide esto únicamente con un error intencional de un proveedor que no sea de producción. La documentación de LiteLLM advierte que las marcas de alternativas simuladas antiguas no prueban las solicitudes del proxy; un fallo real y controlado es la vía adecuada para validar el proxy.

Mantenga las condiciones 404, de autenticación, permisos, esquema y políticas de contenido fuera de un bucle general de reintentos, salvo que haya diseñado explícitamente una respuesta independiente. La documentación de enrutamiento de LiteLLM admite políticas de reintento específicas para cada error, incluidos cero reintentos para NotFoundError; esto evita que un nombre de modelo no válido se convierta en un incidente lento.

Antes de habilitar una alternativa entre proveedores, valide el contrato del producto:

• Comportamiento de la ventana de contexto y semántica de las llamadas a herramientas
• Compatibilidad con salida estructurada y formato de respuesta
• Requisitos de residencia de datos, retención y políticas de clientes
• Comportamiento de seguridad y expectativas de las políticas de contenido
• Límites de latencia y coste
• Idempotencia de los efectos secundarios posteriores

Las alternativas deben ser observables después de la solicitud, no silenciosas. LiteLLM documenta campos como las alternativas intentadas y el grupo de modelos original en los metadatos del registro de gasto. Supervise la tasa de alternativas, la tasa de éxito final, la latencia añadida por reintento/alternativa y el coste de la ruta que realmente atendió la solicitud.

Para un diseño de enrutamiento más amplio, consulte la guía práctica de enrutamiento con alternativas de Flatkey. Se aplica la misma regla: enrute únicamente cuando la alternativa siga cumpliendo el contrato del flujo de trabajo.

Una lista de verificación preparada para incidentes de problemas de LiteLLM

Ejecute esta lista de verificación antes de cerrar un incidente o declarar corregido uno de los errores comunes de LiteLLM.

Cuándo simplificar la superficie de enrutamiento

Algunos equipos quieren LiteLLM porque centraliza la configuración de modelos, el uso y la política de fiabilidad. Otros quieren menos infraestructura de puerta de enlace que operar. La respuesta adecuada depende de quién es responsable de la política de enrutamiento, las credenciales de los proveedores, la aplicación del presupuesto y el ciclo de respuesta a incidentes.

Flatkey es útil cuando una aplicación necesita una superficie de integración compatible con OpenAI en las rutas de modelos compatibles, manteniendo el enrutamiento, la revisión de uso y la facturación más estrechamente integrados. No elimina la necesidad de clasificar los tiempos de espera, los bloqueos de presupuesto o los errores de proveedores; reduce la cantidad de integraciones de cliente específicas de cada proveedor que su aplicación debe mantener. Comience con una clave API para varios modelos de IA o la guía de inicio rápido de la API de Flatkey cuando quiera evaluar ese modelo operativo.

Para obtener una guía completa de configuración y un ejemplo de configuración, consulte nuestra guía del proxy de LiteLLM.

Preguntas frecuentes

¿Es seguro reintentar todos los errores comunes de LiteLLM?

No. Los fallos de autenticación, permisos, modelo no válido, parámetro no compatible, presupuesto y la mayoría de los fallos de facturación requieren una corrección de configuración o cuenta. Reintente solo condiciones claramente transitorias, con un presupuesto reducido de intentos y tiempo, y únicamente cuando sea seguro repetir la operación.

¿Por qué max_budget no detiene el gasto en mi proxy de LiteLLM?

Primero, verifique que el proxy cuente con el seguimiento de gastos respaldado por base de datos necesario para aplicar presupuestos. Luego, confirme que el tráfico llegue a LiteLLM en lugar de llamar directamente a un proveedor, y que la clave, equipo, usuario o proyecto configurado sea el ámbito que realmente realiza la solicitud. La documentación sobre presupuestos de LiteLLM explica el requisito de base de datos y el comportamiento del ámbito.

¿Son suficientes las alertas de presupuesto de Azure o AWS para evitar que una aplicación exceda su presupuesto?

Son útiles como salvaguardas a nivel de cuenta del proveedor, pero no determinan si se debe admitir una solicitud específica de la puerta de enlace. Mantenga las alertas de facturación del proveedor y añada luego un presupuesto de puerta de enlace probado y un límite de producto a nivel de aplicación donde se conozca el contexto de la solicitud.

¿Qué debo guardar de una llamada fallida a LiteLLM?

Guarde el cuerpo del error depurado, la clase de excepción normalizada, el estado HTTP, el nombre del proveedor, el modelo solicitado, la marca de tiempo, el entorno, el número de intento del cliente y x-litellm-call-id cuando esté disponible. Evite registrar claves API y contenido confidencial de prompts/respuestas.

¿Puede un mecanismo de respaldo ocultar una mala configuración?

Sí. Un mecanismo de respaldo puede hacer que la solicitud de un cliente tenga éxito mientras la ruta principal sigue fallando. Por eso la tasa de respaldo, los errores específicos de cada ruta, el grupo de modelos final, la latencia y el coste necesitan alertas o paneles. Trate una tasa de respaldo creciente como una señal operativa, no como una solución completada.

Conclusión final

La solución duradera para los errores comunes de LiteLLM no es un número universal de reintentos ni un tiempo de espera mayor. Es un ciclo operativo repetible: capturar el fallo real, identificar la capa de políticas, validar el cambio seguro más pequeño y demostrar la ruta de recuperación con una prueba controlada. Esto mantiene los tiempos de espera acotados, las alertas de presupuesto relevantes y los fallos de proveedores lo bastante visibles como para corregirlos.

Fuentes

• Mapeo de excepciones de LiteLLM
• Presupuestos y límites de tasa de LiteLLM
• Conmutación por error y mecanismos de respaldo de proveedores de LiteLLM
• Enrutamiento, reintentos, periodos de enfriamiento y concurrencia de LiteLLM
• Prácticas recomendadas de LiteLLM para producción
• Registro de LiteLLM
• Comprobaciones de la tasa de captura de gasto de LiteLLM