Erreurs courantes de LiteLLM : délais d’attente, alertes de budget et échecs de fournisseurs

Erreurs courantes de LiteLLM : délais d’attente, alertes de budget et échecs de fournisseurs

La plupart des erreurs courantes de LiteLLM ressemblent d’abord à un problème de fournisseur : une requête expire, une alerte de budget n’arrive jamais, ou un modèle fonctionnel renvoie soudainement une erreur 404 ou 503. La solution la plus rapide consiste à identifier la couche de contrôle défaillante avant de modifier les nouvelles tentatives ou de changer de modèle.

Utilisez ce guide pour distinguer les délais côté client, la politique de la passerelle LiteLLM, la configuration du modèle, la capacité du fournisseur et l’application des limites de dépenses. Il inclut un petit workflow d’incident que vous pouvez répéter pour les délais d’attente, les contrôles budgétaires et les défaillances de fournisseurs.

Réponse rapide : Conservez une requête ayant échoué, classez l’erreur, reproduisez-la avec un appel minimal et modifiez un seul contrôle à la fois. Commencez par le type d’exception normalisé de LiteLLM, les métadonnées de la requête et l’ID d’appel, et non uniquement par le statut HTTP.

LiteLLM mappe de nombreuses défaillances de fournisseurs vers des types d’exceptions compatibles avec OpenAI et expose le statut HTTP, le message et le fournisseur d’origine sur l’exception. Cela facilite le dépannage des erreurs courantes de LiteLLM lorsque vous conservez intact le contexte d’erreur d’origine au lieu de le remplacer par une erreur générique 500. Consultez la référence de mappage des exceptions LiteLLM pour le mappage actuel.

La matrice des erreurs courantes de LiteLLM

Ce tableau constitue le principal atout de ce guide sur les erreurs courantes de LiteLLM : il transforme une défaillance vague de passerelle en prochaine observation précise.

Un flux de triage LiteLLM Common Errors en cinq minutes

Avant de modifier config.yaml, enregistrez un échec représentatif. Masquez les secrets et le contenu des prompts si nécessaire, mais conservez les champs opérationnels.

1. Capturez l’identité de la requête. Notez l’horodatage, l’environnement, la route, le model demandé, le statut HTTP, le type d’exception LiteLLM, le message d’erreur, le nom du fournisseur et le numéro de tentative du client.
2. Capturez l’identité de la passerelle. Enregistrez x-litellm-call-id lorsqu’il est présent. LiteLLM documente cet en-tête comme le meilleur identifiant pour suivre une requête dans les systèmes de journalisation. Notez également x-litellm-model-id, x-litellm-model-api-base et les en-têtes de version si votre réponse les expose. La documentation de journalisation LiteLLM répertorie les en-têtes actuels.
3. Classez la défaillance. S’agit-il d’une requête non valide, d’un problème d’authentification/d’autorisation, d’une limite de budget/de débit, d’un délai d’attente ou d’une défaillance du service en amont ? Ne placez pas toutes les erreurs 4xx dans la même catégorie de nouvelles tentatives.
4. Effectuez une reproduction minimale hors production. Utilisez la même clé virtuelle et le model_name public que l’application utilise. Supprimez la concurrence spécifique à l’application et les appels d’outils avant de tester une requête de base.
5. Ne modifiez qu’une seule couche. Une correction de nom de modèle, une modification du délai d’attente et un changement de repli dans le même déploiement rendent le résultat final impossible à expliquer.

Voici une sonde minimale générique pour un proxy LiteLLM compatible avec 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
  }'

L’essentiel n’est pas que support-chat soit un nom de modèle universel. L’essentiel est que le test utilise le nom public configuré dans votre passerelle, puis conserve les en-têtes et le corps de la réponse afin de les comparer à la requête applicative ayant échoué.

Erreurs de délai d’attente : identifiez l’échéance qui s’est réellement déclenchée

Les délais d’attente comptent parmi les erreurs courantes de LiteLLM les plus trompeuses, car une requête peut expirer à plusieurs niveaux :

• L’appelant peut annuler en premier.
• Le déploiement ou le routeur LiteLLM peut appliquer une échéance plus courte.
• Le paramètre request_timeout du proxy peut interrompre un appel en amont de longue durée.
• Le fournisseur, l’équilibreur de charge ou le chemin réseau peut fermer la requête.
• Une réponse en streaming peut démarrer correctement, puis se bloquer entre deux fragments.

La documentation de mappage des exceptions de LiteLLM répertorie les échecs de délai d’attente sous la forme openai.APITimeoutError. Pour les routes natives et de relais direct, l’actuelle documentation sur les délais d’attente décrit un ordre de priorité entre les paramètres de requête, de déploiement, de routeur et de proxy. Vérifiez la version de la documentation correspondant à votre déploiement avant d’appliquer une modification de configuration.

Commencez par un budget d’échéance, pas par un nombre plus élevé

Choisissez la latence totale que votre parcours utilisateur peut tolérer, puis répartissez-la à rebours. Par exemple, une expérience interactive peut réserver du temps pour la mise en file d’attente, une nouvelle tentative et le rendu de la réponse, au lieu de laisser l’appel en amont consommer toute l’échéance visible par l’utilisateur.

# Point de départ indicatif — adaptez-le à votre charge de travail et à votre version de LiteLLM.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

L’exemple est volontairement prudent : il donne au proxy un mode d’échec borné au lieu de laisser les connexions rester bloquées. Les recommandations pour la production de LiteLLM préconisent de définir un délai d’attente de requête et d’utiliser une journalisation structurée en production.

Lorsqu’un délai d’attente survient, répondez à ces questions dans l’ordre :

Ne laissez pas une nouvelle tentative automatisée après expiration se poursuivre indéfiniment. Une nouvelle tentative n’est raisonnable que si le travail peut être répété sans risque et qu’une autre tentative peut encore se terminer avant l’échéance de l’appelant. Si une requête déclenche des outils, écrit des données ou commence un flux visible par l’utilisateur, définissez d’abord l’idempotence et la sémantique de redémarrage.

Pour les problèmes de mise en file d’attente ou de capacité entraînés par des 429 et se manifestant par une latence élevée, associez cette section au guide de Flatkey sur les RPM, TPM et nouvelles tentatives. Un délai d’attente peut être le symptôme d’un contrôle d’admission surchargé, et non d’un paramètre de durée de requête.

Alertes de budget : séparez la notification de l’application des règles

Le comportement des budgets est à l’origine d’une part disproportionnée des erreurs courantes de LiteLLM, car les équipes regroupent souvent trois contrôles distincts sous le terme « alerte ». Ils ne sont pas interchangeables.

Première vérification de budget : existe-t-il une base de données ?

L’actuelle documentation sur les budgets de LiteLLM est explicite : les budgets de son proxy sont appliqués à partir des dépenses lues dans la base de données. Dans un déploiement sans base de données, un max_budget global configuré ne constitue pas un plafond de dépenses fiable ; le comportement des budgets des clés virtuelles, des équipes et des utilisateurs dépend également de la base de données.

Cela conduit à un schéma d’échec courant : une équipe définit max_budget, voit un avertissement au démarrage ou une valeur de configuration, et suppose que le trafic de production s’arrêtera au seuil. Ce ne sera pas un contrôle fiable sans la configuration requise de suivi des dépenses.

# 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

Considérez fail_closed_budget_enforcement comme une décision de fiabilité, et non comme une correction à copier-coller. La documentation actuelle de LiteLLM explique qu'une vérification plus stricte du budget peut rejeter des requêtes lorsque la dépense ne peut pas être vérifiée ; testez le comportement en cas de défaillance de la base de données et de Redis pour votre déploiement avant de l'activer à grande échelle.

Testez le parcours du budget, pas seulement le tableau de bord

Utilisez une clé ou une équipe jetable dans un environnement hors production et vérifiez cette séquence :

1. Confirmez que le proxy peut lire et écrire dans le stockage des dépenses.
2. Créez un budget strict volontairement faible dans le périmètre approprié : clé, équipe, utilisateur, projet ou utilisateur final.
3. Envoyez une requête minimale via le proxy.
4. Envoyez une deuxième requête qui doit dépasser le seuil.
5. Vérifiez indépendamment l'exception renvoyée, l'enregistrement de dépense, la fenêtre de réinitialisation et le canal d'alerte.
6. Confirmez que l'application gère un blocage de budget sans le réessayer comme s'il s'agissait d'une surcharge transitoire du fournisseur.

LiteLLM documente également les fenêtres budgétaires et les contrôles de budget par modèle. Soyez précis quant au calendrier de réinitialisation : un garde-fou quotidien et un plafond mensuel répondent à des risques différents.

Les alertes de budget Azure et les alertes de budget AWS sont des filets de sécurité, pas des remplacements

Les mots-clés secondaires alertes de budget Azure et alertes de budget AWS sont importants, car les alertes de facturation des fournisseurs cloud couvrent une limite différente. Elles peuvent avertir en cas de dépenses au niveau du compte fournisseur ou de l'abonnement, y compris pour le trafic qui contourne LiteLLM. Elles ne remplacent pas une décision au niveau de la passerelle quant à savoir si cette requête, cette clé, ce locataire ou ce modèle doit être admis maintenant.

Utilisez les deux couches lorsque cela est approprié :

• La politique de budget LiteLLM protège la route et le locataire que la passerelle peut identifier.
• Les alertes de budget Azure ou les alertes de budget AWS surveillent les dépenses du compte cloud en amont.
• Un registre d'utilisation de la passerelle réconcilie les deux et révèle le trafic qui a contourné le chemin prévu.

Pour les dépenses OpenAI, la vérification du taux de capture des dépenses de LiteLLM peut comparer les dépenses suivies avec l'API OpenAI Organization Costs. Elle a actuellement des prérequis spécifiques au fournisseur ; lisez donc la documentation versionnée avant de la considérer comme une fonctionnalité universelle de rapprochement multi-fournisseurs.

Si le besoin opérationnel dépasse un seul déploiement LiteLLM, consultez le guide d'évaluation des tableaux de bord unifiés de facturation IA pour connaître les questions à poser concernant les clés, les budgets, les allocations, les alertes et le rapprochement.

Échecs de fournisseur : vérifiez séparément le nom public du modèle et le déploiement en amont

Les échecs de fournisseur sont les LiteLLM Common Errors les plus visibles, mais il s'agit souvent d'erreurs de configuration de la passerelle. Un client appelle généralement le model_name public que vous exposez. LiteLLM résout ensuite ce nom en un modèle fournisseur, un déploiement, un point de terminaison, un identifiant et des paramètres spécifiques au fournisseur.

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

model_name et litellm_params.model sont délibérément des concepts différents. Lorsqu'un client reçoit une erreur de modèle non valide, comparez d'abord le nom exact demandé avec model_name. La documentation de gestion des modèles de LiteLLM distingue le nom de modèle public du modèle fournisseur et propose un processus de test de connexion pour les modèles configurés.

Tableau de décision pour les échecs de fournisseur

Le type d’exception doit guider l’action suivante. La référence des exceptions de LiteLLM associe les conditions 401, 402, 403, 404, 408, 429, 500 et 503 à des classes normalisées ; elle expose également des champs spécifiques aux fournisseurs pour une investigation plus approfondie.

Nouvelles tentatives, basculements et périodes de refroidissement : rétablir le service sans masquer l’incident

Les nouvelles tentatives et les basculements peuvent réduire les échecs visibles, mais ils peuvent aussi transformer une erreur de configuration en latence, en coût ou en travail dupliqué. Une bonne gestion des erreurs courantes de LiteLLM applique une politique différente pour une configuration non valide et pour une courte interruption du fournisseur.

LiteLLM documente une distinction utile :

• Les nouvelles tentatives tentent de rétablir la requête au sein du groupe de modèles actuel.
• Les basculements passent à un autre groupe de modèles après les nouvelles tentatives configurées.
• Les périodes de refroidissement isolent un déploiement défaillant tout en maintenant des alternatives saines disponibles.

Voici une petite configuration illustrative basée sur le guide de basculement de fournisseur 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

Validez cela uniquement avec une erreur de fournisseur intentionnelle et hors production. La documentation de LiteLLM avertit que les anciens indicateurs de basculement simulé ne testent pas les requêtes proxy ; une défaillance réelle et contrôlée constitue la méthode de validation appropriée pour le proxy.

Gardez les conditions 404, d’authentification, d’autorisation, de schéma et de politique de contenu hors d’une boucle générale de nouvelles tentatives, sauf si vous avez explicitement conçu une réponse distincte. La documentation de routage de LiteLLM prend en charge des politiques de nouvelles tentatives spécifiques aux erreurs, y compris zéro nouvelle tentative pour NotFoundError ; cela empêche qu’un nom de modèle non valide ne se transforme en incident lent.

Avant d’activer un basculement entre fournisseurs, validez le contrat produit :

• Le comportement de la fenêtre de contexte et la sémantique des appels d’outils
• La prise en charge des sorties structurées et du format de réponse
• Les exigences de résidence des données, de conservation et de politique client
• Le comportement de sécurité et les attentes relatives aux politiques de contenu
• Les limites de latence et de coût
• L’idempotence des effets secondaires en aval

Les basculements doivent être observables après la requête, et non silencieux. LiteLLM documente des champs tels que les basculements tentés et le groupe de modèles d’origine dans les métadonnées des journaux de dépenses. Surveillez le taux de basculement, le taux de réussite final, la latence ajoutée par les nouvelles tentatives et les basculements, ainsi que le coût de la route qui a effectivement traité la requête.

Pour une conception de routage plus large, consultez le guide pratique de routage avec basculement de Flatkey. La même règle s’applique : n’acheminez que si l’alternative respecte toujours le contrat du flux de travail.

Une checklist prête pour les incidents liés à LiteLLM

Exécutez cette checklist avant de clôturer un incident ou de déclarer l’une des erreurs courantes de LiteLLM résolue.

Quand simplifier la surface de routage

Certaines équipes veulent LiteLLM parce qu’il centralise la configuration des modèles, l’utilisation et la politique de fiabilité. D’autres souhaitent avoir moins d’infrastructure de passerelle à exploiter. La bonne réponse dépend de la personne qui est responsable de la politique de routage, des identifiants des fournisseurs, de l’application des budgets et de la boucle de réponse aux incidents.

Flatkey est utile lorsqu’une application a besoin d’une surface d’intégration compatible avec OpenAI sur les routes de modèles prises en charge, tout en rapprochant le routage, l’examen de l’utilisation et la facturation. Il ne supprime pas la nécessité de classifier les délais d’attente, les blocages de budget ou les erreurs de fournisseur ; il réduit le nombre d’intégrations clientes spécifiques aux fournisseurs que votre application doit maintenir. Commencez par une clé API pour plusieurs modèles d’IA ou le guide de démarrage rapide de l’API Flatkey si vous souhaitez évaluer ce modèle opérationnel.

Pour une procédure complète de configuration et un exemple de configuration, consultez notre guide du proxy LiteLLM.

FAQ

Peut-on réessayer sans risque toutes les erreurs courantes de LiteLLM ?

Non. Les échecs d’authentification, d’autorisation, de modèle non valide, de paramètre non pris en charge, de budget et la plupart des échecs de facturation nécessitent une correction de la configuration ou du compte. Ne réessayez que les conditions clairement transitoires, avec un budget limité de tentatives et de temps, et uniquement lorsque l’opération peut être répétée sans risque.

Pourquoi max_budget n’empêche-t-il pas les dépenses dans mon proxy LiteLLM ?

Vérifiez d’abord que le proxy dispose du suivi des dépenses adossé à une base de données requis pour l’application des budgets. Confirmez ensuite que le trafic passe par LiteLLM plutôt que d’appeler directement un fournisseur, et que la clé, l’équipe, l’utilisateur ou le projet configuré correspond bien au périmètre qui effectue réellement la requête. La documentation sur les budgets de LiteLLM explique l’exigence de base de données et le comportement des périmètres.

Les alertes de budget Azure ou AWS suffisent-elles à empêcher un dépassement par une application ?

Elles constituent des garde-fous utiles au niveau du compte fournisseur, mais elles ne déterminent pas si une requête spécifique vers la passerelle doit être acceptée. Conservez les alertes de facturation du fournisseur, puis ajoutez un budget de passerelle testé et une limite de produit au niveau de l’application, là où le contexte de la requête est connu.

Que dois-je conserver d’un appel LiteLLM en échec ?

Conservez le corps d’erreur assaini, la classe d’exception normalisée, le statut HTTP, le nom du fournisseur, le modèle demandé, l’horodatage, l’environnement, le numéro de tentative du client et x-litellm-call-id lorsqu’il est disponible. Évitez de consigner les clés API ainsi que le contenu sensible des prompts et des réponses.

Un mécanisme de repli peut-il masquer une mauvaise configuration ?

Oui. Un mécanisme de repli peut permettre à une requête client de réussir tandis que la route principale continue d’échouer. C’est pourquoi le taux de repli, les erreurs spécifiques aux routes, le groupe de modèles final, la latence et le coût doivent faire l’objet d’alertes ou de tableaux de bord. Considérez l’augmentation du taux de repli comme un signal opérationnel, et non comme un problème résolu.

Conclusion

La solution durable aux erreurs courantes de LiteLLM n’est ni un nombre universel de tentatives ni un délai d’attente plus long. Il s’agit d’une boucle opérationnelle reproductible : capturer l’échec réel, identifier la couche de politique concernée, valider la plus petite modification sûre et prouver le chemin de récupération à l’aide d’un test contrôlé. Cela permet de maintenir des délais d’attente limités, des alertes de budget pertinentes et des échecs de fournisseurs suffisamment visibles pour être corrigés.

Sources

• Mappage des exceptions LiteLLM
• Budgets et limites de débit LiteLLM
• Basculement de fournisseur et mécanismes de repli LiteLLM
• Routage, nouvelles tentatives, périodes de refroidissement et concurrence dans LiteLLM
• Bonnes pratiques de production LiteLLM
• Journalisation LiteLLM
• Vérifications du taux de capture des dépenses LiteLLM