Avant de diagnostiquer une erreur de l'API Llama, vérifiez un point : l'aperçu public de l'API Llama de Meta a été arrêté le 6 juillet 2026. Si vous continuez d'appeler l'ancienne adresse, vous obtenez souvent non pas un 401 ou un 429, mais un message d'arrêt ou une redirection. Beaucoup de diagnostics « clé invalide » ou « modèle inexistant » correspondent en réalité à des appels vers un point de terminaison hors service.

Aujourd'hui, les modèles Llama sont généralement appelés via un hébergeur tiers, un service d'inférence auto-hébergé ou une passerelle unifiée. L'authentification, l'URL de base, les identifiants de modèle, les règles de limitation et la structure des erreurs varient d'une plateforme à l'autre : il n'existe pas de tableau d'erreurs universel. Cet article distingue cinq familles — 401, 404, 429, délais et erreurs 400 liées aux appels d'outils — et propose un ordre de diagnostic ainsi qu'un code de gestion des erreurs réutilisable. Les modèles et les tarifs sont à consulter sur la page tarifs des modèles.

Remarque : Llama est une marque de Meta Platforms, Inc. Les interfaces, codes d'erreur et règles de limitation des hébergeurs peuvent évoluer. Les cas décrits reflètent la situation courante en octobre 2026 ; la documentation de la plateforme concernée fait foi.

1. Identifier d'abord la couche où survient l'erreur

Un même échec peut avoir des causes très différentes. Examinez le code de statut, le type d'erreur et l'identifiant de requête avant de décider s'il faut modifier la configuration, le code ou changer de plateforme.

Symptôme Signification fréquente À vérifier en priorité
Message d'arrêt ou redirection Requête vers un point de terminaison arrêté Domaine et URL de base
401 Échec d'authentification Clé, en-têtes, appariement plateforme
404 Chemin ou modèle inexistant URL de base, chemin, identifiant de modèle
429 Limitation ou quota atteint Concurrence, clé partagée, stratégie de retry
400 avec context length Contexte dépassé Longueur d'entrée, réserve de sortie
400 avec tool ou JSON Format d'appel d'outil invalide Schéma des paramètres, parsing, retry
Délai Connexion, premier token ou lecture Réseau, longueur d'entrée, timeouts
5xx Erreur du service amont Retry avec backoff, page de statut

Les journaux doivent au minimum enregistrer l'horodatage, la plateforme, l'URL de base, l'identifiant de modèle, le code de statut, le type d'erreur, la durée et l'identifiant de requête. N'enregistrez jamais la clé complète ni le texte original de l'utilisateur.

2. 401 : la clé et la plateforme doivent correspondre

Un 401 signifie que l'identité n'a pas été validée ; cela n'a généralement rien à voir avec les capacités du modèle ou le solde. Llama n'a pas de clé universelle : une clé de l'ancienne plateforme Meta ne fonctionne pas chez un hébergeur tiers, et inversement. Autres causes fréquentes :

  • L'en-tête n'utilise pas Authorization: Bearer <key>, ou la casse et l'orthographe sont incorrectes.
  • La clé contient des espaces, un saut de ligne ou des guillemets, fréquent après un copier-coller depuis une fenêtre de chat.
  • La variable d'environnement n'est pas réellement chargée et l'environnement déployé conserve l'ancienne valeur.
  • La clé a été supprimée, renouvelée ou désactivée, mais une tâche planifiée utilise encore l'ancienne.
  • Un reverse proxy ou une passerelle écrase ou supprime l'en-tête Authorization.
  • L'état du compte ou les droits régionaux posent problème : la clé est valide mais n'a pas accès au modèle.

Commencez par une requête curl minimale pour confirmer simultanément la clé, l'URL de base et l'identifiant de modèle. Si le 401 persiste, testez une nouvelle clé pour distinguer le problème de clé, de proxy ou de passerelle. Ne codez jamais la clé en dur dans le client et ne la laissez pas côté front-end.

3. 404 : URL de base, nom de modèle et points de terminaison arrêtés

Un 404 ne signifie généralement pas que le modèle est cassé, mais que la requête vise une adresse ou un modèle inexistant. En 2026, le cas le plus courant est l'ancienne adresse de première partie de Meta, arrêtée, qui renvoie un 404 ou un message d'arrêt. Autres causes :

  • URL de base d'une autre plateforme, ou /v1 en trop ou manquant.
  • Le SDK ajoute automatiquement /chat/completions et le chemin écrit à la main le duplique.
  • Identifiant de modèle repris de l'ancienne plateforme, inconnu du nouvel hébergeur.
  • Préfixe ou suffixe de version requis, casse ou tirets incohérents.
  • Modèle non disponible dans la région visée ou retiré par la plateforme.
  • Règles de réécriture du reverse proxy qui abîment le chemin.

Les conventions de nommage varient fortement d'une plateforme à l'autre. Mieux vaut maintenir une table de correspondance dans la configuration plutôt que disperser les noms de modèles dans le code. Lors d'un changement, ne modifiez que la table et l'URL de base. En cas de 404, consultez d'abord le catalogue de modèles, puis le chemin ; ne comptez pas sur le retry.

4. 429 : limitation, quotas et tempête de retries

Un 429 indique que la requête dépasse une limite de débit, de concurrence ou de quota. Les règles varient selon les hébergeurs : requêtes par minute, tokens par minute, quota quotidien ou niveau de compte. Consultez la documentation de la plateforme. Scénarios courants :

  • Plusieurs services partagent une clé et se disputent le quota.
  • Des lots de tâches démarrent à la même heure, créant un pic de trafic.
  • Les retries n'ont pas de backoff et amplifient l'échec.
  • Un contexte ou une sortie longue consomme beaucoup de tokens et réduit la marge de concurrence.
  • Le quota gratuit ou d'essai est épuisé, mais la plateforme renvoie encore 429 ou un code approchant.

Ordre de traitement : réduire d'abord la concurrence, ajouter ensuite un backoff exponentiel avec jitter, et seulement enfin envisager de séparer les clés ou d'augmenter le quota. Séparer les clés ne règle que les conflits de partage, pas le dépassement global. Le monitoring doit isoler le taux de 429 par plateforme, modèle et projet, sinon il est difficile d'identifier le consommateur.

5. Délais : connexion, premier token, lecture et streaming

Un délai n'équivaut pas à une indisponibilité. Localisez d'abord le segment bloqué :

  • Délai de connexion : DNS, sortie ou proxy injoignable, la requête n'atteint pas la plateforme.
  • Premier token lent : entrée trop longue, file d'attente de la plateforme, charge élevée du modèle.
  • Délai de lecture : sortie trop longue, inférence longue, connexion coupée par un équipement intermédiaire.
  • Flux interrompu : gigue réseau ou proxy qui coupe, contenu partiel reçu.
  • Délais simultanés partout : sortie locale ou panne amont, consultez d'abord la page de statut.

Réglez séparément les délais de connexion et de lecture. Une valeur unique très élevée bloque le pool de threads en cas de panne ; une valeur trop basse tue des tâches longues légitimes. Pour le streaming, enregistrez le contenu reçu et la position d'interruption, prenez en charge la reconnexion et la déduplication, et n'insérez jamais un contenu partiel en base.

6. 400 : contexte dépassé et format des appels d'outils

Un 400 couvre un large spectre ; cherchez d'abord les mots-clés du message. Si context length, maximum tokens ou input too long apparaissent, le contexte est probablement dépassé : entrée plus réserve de sortie au-delà de la limite du modèle. Comptez les tokens, tronquez l'historique, compressez le contenu récupéré ou passez à un modèle à contexte plus long. N'augmentez pas seulement max_tokens, cela réduit l'espace d'entrée.

Si tool, function, arguments ou JSON apparaissent, le format d'appel d'outil est probablement invalide : JSON non analysable, champ obligatoire manquant, type de paramètre incorrect ou nom d'outil inexistant. Principes de traitement :

  1. Validez les paramètres avec un schéma JSON, sans concaténation de chaînes.
  2. En cas d'échec de parsing, renvoyez au modèle le message d'erreur et le format attendu pour une correction unique.
  3. Limitez le nombre de corrections pour éviter les boucles infinies.
  4. Enregistrez la réponse brute pour distinguer un problème de modèle d'un problème de prompt.
  5. Pour les outils à risque, ajoutez une validation secondaire ; ne croyez pas le modèle lorsqu'il déclare avoir exécuté l'action.

7. Code de gestion des erreurs réutilisable

L'exemple utilise une interface compatible OpenAI ; l'URL de base et l'identifiant de modèle viennent de variables d'environnement. Le retry automatique du SDK est désactivé pour éviter le cumul avec le backoff personnalisé.

import os
import random
import time
import logging
from openai import (
    OpenAI, AuthenticationError, NotFoundError, RateLimitError,
    BadRequestError, APITimeoutError, APIStatusError,
)

logging.basicConfig(level=logging.INFO)
client = OpenAI(
    api_key=os.environ["LLAMA_HOST_API_KEY"],
    base_url=os.environ["LLAMA_HOST_BASE_URL"],  # adresse compatible de l'hébergeur
    max_retries=0,
    timeout=90,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["LLAMA_MODEL_ID"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except AuthenticationError:
            raise  # clé et plateforme incompatibles, le retry est inutile
        except NotFoundError as exc:
            logging.error("Vérifier l'URL de base et l'identifiant de modèle : %s", exc.request_id)
            raise
        except BadRequestError as exc:
            logging.error("Paramètres, contexte ou format d'appel d'outil invalides : %s", exc.request_id)
            raise
        except (RateLimitError, APITimeoutError) as exc:
            wait = min(2 ** attempt, 20) + random.random()
            logging.warning("Échec n° %s, nouvelle tentative dans %.1f s : %s",
                            attempt + 1, wait, exc.request_id)
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                logging.warning("Amont %s, nouvelle tentative dans %.1f s", exc.status_code, wait)
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Nombre de tentatives épuisé, vérifiez la limitation et les timeouts")

Le retry ne convient qu'aux erreurs transitoires. Les 401, 404 et la plupart des 400 ne s'améliorent pas avec un retry ; ils gonflent seulement les journaux et la facture. Pour les opérations à effet de bord, utilisez une clé d'idempotence ou une vérification d'état avant de renvoyer.

8. Journaux, monitoring et ordre de diagnostic

Procédez dans cet ordre pour éviter de changer de modèle dès le premier échec :

  1. Enregistrez code de statut, type d'erreur, identifiant de requête, plateforme, URL de base, identifiant de modèle et horodatage.
  2. Si les requêtes visent l'ancienne adresse de première partie, terminez d'abord la migration.
  3. Pour un 401, vérifiez clé, en-têtes, variables d'environnement et appariement de plateforme.
  4. Pour un 404, vérifiez l'URL de base, le chemin /v1 et le catalogue actuel de modèles.
  5. Pour un 429, vérifiez concurrence, clé partagée, stratégie de retry et heures de pointe.
  6. Pour un délai, vérifiez DNS, proxy, longueur d'entrée, temps du premier token et timeout de lecture.
  7. Pour un 400, vérifiez longueur de contexte, paramètres pris en charge et schéma d'outil.
  8. Pour un 5xx, appliquez d'abord le backoff ; si cela persiste, contactez la plateforme avec l'identifiant de requête.

Le monitoring doit au minimum agréger par heure les 401, 404, 429, délais et 5xx, en les séparant par plateforme et par modèle. En cas de pic du taux d'erreur, vérifiez d'abord s'il se concentre sur un projet, une clé ou un modèle, puis décidez de réduire la concurrence, de changer de canal ou de revenir en arrière.

Questions fréquentes

Un 401 de l'API Llama signifie-t-il que la clé a expiré ?

Pas nécessairement. Le cas le plus fréquent est une incompatibilité entre la clé et la plateforme, par exemple une clé de l'ancienne plateforme Meta utilisée chez un hébergeur tiers, ou l'inverse. Vérifiez l'en-tête, les variables d'environnement et la plateforme d'origine, puis retestez avec une requête minimale.

Pourquoi un 404 après un changement d'hébergeur ?

L'identifiant de modèle a changé. Les conventions de nommage, préfixes, suffixes de version et régions disponibles diffèrent ; l'ancien nom n'existe généralement pas sur la nouvelle plateforme. Tenez une table de correspondance et fiez-vous au catalogue du nouvel hébergeur.

Faut-il réessayer immédiatement après un 429 ?

Non, pas en rafale. Réduisez d'abord la concurrence, puis appliquez un backoff exponentiel avec jitter et une limite. Un 429 persistant indique un dépassement global ou de quota : séparez les clés, décalez les pics ou ajustez le quota.

Peut-on réessayer indéfiniment en cas de délai ?

Non. Le retry doit avoir une limite, un backoff et des alertes. Un délai peut aussi signifier que la requête a déjà été exécutée en amont ; pour les opérations à effet de bord, vérifiez l'état avant de renvoyer.

Que faire si le JSON des paramètres d'un appel d'outil ne se parse pas ?

Validez avec un schéma JSON et conservez la réponse brute ; renvoyez ensuite au modèle le message d'erreur et le format attendu pour une correction unique, en limitant le nombre d'essais. Les outils à risque exigent une validation secondaire, même si le modèle déclare avoir réussi.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, entraînez-vous sur un 401, un 404, un 429, un délai et un échec d'appel d'outil, puis branchez le monitoring de production. La disponibilité des modèles et les tarifs sont indiqués sur la page tarifs des modèles.

Lectures associées :