Les erreurs de l'API GLM se lisent sur deux niveaux : le code de statut HTTP à l'extérieur, et le code métier dans le corps de réponse à l'intérieur. Ne regarder que le premier conduit vite à une mauvaise interprétation : un compte impayé renvoie par exemple aussi un 429. L'ordre de diagnostic doit être : lire d'abord le code métier et le message, retrouver ensuite l'identifiant de requête ou d'erreur, reproduire avec une requête minimale, et seulement ensuite modifier les paramètres ou le modèle.

Cet article détaille 401, 403, 404, 429, 5xx et timeouts, avec une table de correspondance des codes métier, du code de gestion d'erreurs et une liste à préparer avant de contacter le support. Les modèles et les tarifs font foi sur la page Tarifs des modèles.

Remarque : Zhipu, GLM et BigModel sont des marques de leurs détenteurs respectifs. Cet article est purement technique et n'a aucun lien d'affiliation ni de représentation avec Zhipu. Les codes d'erreur, règles de limitation et comportements d'interface peuvent évoluer selon les versions ; la documentation du fournisseur et la réponse réelle font foi.

1. Distinguer d'abord les deux niveaux d'erreur

Le code HTTP décrit l'issue au niveau du protocole ; le code métier décrit la cause précise. Un même 401 peut signifier un en-tête d'authentification absent, un token expiré ou une double authentification ; un même 429 peut signifier une limitation, un modèle surchargé, un impayé ou un plafond d'offre. Journaliser le code métier est l'étape la plus efficace du diagnostic.

HTTP Codes métier courants Signification Nouvelle tentative pertinente
401 1000 / 1001 / 1003 / 1005 Échec d'authentification, en-tête absent, token expiré, double authentification Non, corriger les identifiants
403 1220 Pas de droit d'accès à cette API ou ce modèle Non, vérifier offre et permissions
400 1210 / 1211 / 1221 / 1222 / 1261 Paramètre incorrect, modèle inexistant, API retirée ou absente, prompt trop long Non, corriger la requête
429 1113 Compte impayé Non, recharger d'abord
429 1302 / 1305 Limitation de débit, modèle très sollicité Oui, après backoff
429 1308 / 1310 Plafond de période, réinitialisation selon next_flush_time Attendre la réinitialisation, pas de tentative forcée
429 1311 / 1313 / 1315 Modèle absent de l'offre, limitation d'usage équitable, type de clé incompatible Non, vérifier offre et clé
500 1200 / 1230 / 1234 Erreur interne, erreur de traitement, erreur réseau (avec identifiant) Oui, backoff en conservant l'identifiant

Ce tableau donne les correspondances les plus fréquentes ; la liste complète figure dans la documentation du fournisseur. Une rupture de streaming peut ne pas avoir de code métier : la cause apparaît dans finish_reason ou dans le dernier segment de données.

2. 401 : quatre échecs d'authentification

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. Les codes du fournisseur distinguent les causes courantes :

  • 1000, échec d'authentification : clé erronée, copie incomplète ou clé supprimée.
  • 1001, paramètre d'authentification absent de l'en-tête : pas de Authorization: Bearer <clé>, ou en-tête supprimé par un proxy.
  • 1003, token expiré : la clé a une durée de validité ou a été renouvelée dans la console.
  • 1005, double authentification activée : suivre la procédure de validation de la plateforme.

Procédez dans l'ordre :

  1. Vérifiez le format de l'en-tête : un espace après les deux-points, aucun guillemet ni saut de ligne autour de la clé.
  2. Affichez le préfixe de la variable d'environnement pour confirmer qu'elle n'est ni vide ni obsolète.
  3. Vérifiez le type de clé : API modèle standard, Coding Plan, clé équipe ou entreprise se gèrent séparément et ne se mélangent pas.
  4. Vérifiez que l'URL de base correspond à la clé : clé du fournisseur avec adresse du fournisseur, clé de passerelle avec adresse de passerelle.
  5. Testez une nouvelle clé sur une requête minimale pour distinguer un problème de clé d'un problème de proxy ou de configuration.

Une clé copiée depuis une fenêtre de chat apporte facilement un espace ou un saut de ligne. Commencez par une requête qui ne renvoie qu'un mot : elle élimine la plupart des erreurs de base.

3. 403 et 404 : permissions, chemins et noms de modèles

Le code métier courant d'un 403 est 1220 : le compte n'a pas le droit d'accéder à cette API ou ce modèle. Vérifiez d'abord si l'offre inclut le modèle, si la clé appartient au bon type de produit, puis si l'interface appelée est bien ouverte. Réessayer ne sert à rien : modifiez la permission ou changez de clé.

Un 404 ne signifie pas que « le service est tombé », mais que l'adresse est incorrecte : /v1 en trop ou manquant dans l'URL de base, chemin complet écrit à la main après l'ajout automatique du SDK, règle de réécriture du reverse proxy qui casse le chemin. Chez GLM, un nom de modèle incorrect renvoie généralement un 400 avec le code 1211 ; une API retirée ou inexistante correspond à 1221 et 1222. Donc devant un 404, vérifiez l'adresse ; devant un 1211, vérifiez le nom du modèle.

Le nom du modèle fait foi dans la documentation du fournisseur et sur la page tarifs du site ; n'écrivez pas un numéro de version de mémoire. Avant de mettre à jour un modèle, vérifiez la compatibilité des paramètres dans l'environnement de test.

4. 429 : lire le code métier avant de décider

Le 429 est l'erreur la plus souvent mal traitée. Elle couvre au moins cinq situations :

  • 1113, compte impayé : réessayer avant recharge n'a aucun sens.
  • 1302, limite de débit atteinte : réduire la concurrence ou appliquer un backoff.
  • 1305, modèle très sollicité : souvent lié aux heures de pointe, réessayer après backoff, basculer sur un modèle de secours si nécessaire.
  • 1308 et 1310, plafond d'usage de période atteint : le message contient l'heure de réinitialisation, attendre le rétablissement du quota.
  • 1309, 1311, 1313, 1315 : offre expirée, modèle non ouvert, limitation d'usage équitable ou type de clé incompatible ; seule une modification de configuration aide.

Seules les limitations instantanées comme 1302 et 1305 se prêtent à une nouvelle tentative automatique ; dans les autres cas, réessayer ne fait qu'allonger l'incident. Les règles de limitation (concurrence, requêtes par minute ou débit de tokens) varient selon l'offre et le modèle ; la console et la documentation du fournisseur font foi.

5. 5xx et timeouts : localiser séparément

La série 500 comprend 1200 (erreur interne), 1230 (erreur de traitement) et 1234 (erreur réseau). Le code 1234 s'accompagne généralement d'un identifiant d'erreur, à conserver impérativement pour contacter le support. En cas de 5xx persistant, appliquez d'abord un backoff, puis consultez l'état du service ou les notifications du prestataire, sans réessayer à haute fréquence.

Un timeout se lit en trois segments : le timeout de connexion indique un DNS, une sortie ou un proxy injoignable ; un premier token lent vient souvent d'une file amont ou d'une entrée trop longue ; un timeout de lecture vient d'une sortie trop longue ou d'un raisonnement prolongé. Les traitements diffèrent : augmenter uniquement le timeout global ne suffit pas.

En cas de rupture du streaming, il peut n'y avoir ni code HTTP ni code métier. Notez le contenu déjà reçu et le dernier segment, vérifiez finish_reason, puis déterminez s'il s'agit d'une gigue réseau, d'une coupure du proxy ou d'un timeout amont. Ne stockez pas un contenu partiel comme résultat complet.

6. Identifiants de requête et journaux : les preuves du diagnostic

La réponse du fournisseur ne fournit pas forcément le même nom d'identifiant de requête sur toutes les interfaces ; les noms de champs dépendent de la réponse réelle et de la documentation. La pratique la plus sûre est une double journalisation : un trace_id généré par le client, présent sur toutes les tentatives, et la conservation brute du corps d'erreur amont avec tout champ request id ou error id.

Le journal doit contenir au minimum : heure, trace_id, URL de base, nom du modèle, code HTTP, code métier, message d'erreur, durée, nombre de tentatives et indicateur de streaming. Pour la clé, n'enregistrez que les premiers caractères ou un hachage ; le texte utilisateur et la réponse complète ne doivent pas être écrits en entier sur disque.

Ces champs ne servent pas qu'à vous. Pour contacter le support, une entrée avec trace_id, code métier et requête minimale reproductible est bien plus utile qu'un « il y a parfois une erreur ».

7. Nouvelles tentatives et backoff : exemple de code

Le code ci-dessous désactive les tentatives automatiques du SDK, décide selon le code métier et imprime ensemble trace_id, code de statut et code métier. Les timeouts réseau sont traités séparément, avec un plafond de tentatives.

import os
import random
import time
import uuid

import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url=os.environ.get(
        "GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
    ),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # désactive les tentatives du SDK, gérées ci-dessous
)

RETRYABLE_CODES = {1302, 1305}  # limitation et modèle chargé ; ni impayé ni plafond d'offre

def ask(prompt: str, max_attempts: int = 4) -> str:
    trace_id = uuid.uuid4().hex[:12]
    for attempt in range(1, max_attempts + 1):
        try:
            resp = client.chat.completions.create(
                model=os.environ["GLM_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except APIStatusError as exc:
            code = None
            try:
                code = int(exc.response.json().get("code"))
            except Exception:
                pass
            print(
                f"trace={trace_id} attempt={attempt} "
                f"http={exc.status_code} code={code} "
                f"body={exc.response.text[:500]}"
            )
            retryable = exc.status_code >= 500 or (
                exc.status_code == 429 and code in RETRYABLE_CODES
            )
            if not retryable or attempt == max_attempts:
                raise
        except (APITimeoutError, APIConnectionError) as exc:
            print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
            if attempt == max_attempts:
                raise
        wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
        time.sleep(wait)
    raise RuntimeError("Nombre de tentatives épuisé")

Trois règles complémentaires : respecter en priorité Retry-After renvoyé par le serveur s'il existe ; contrôler globalement le budget de tentatives pour éviter l'empilement entre services ; pour les requêtes à effet de bord, vérifier l'état avec une clé d'idempotence avant de renvoyer.

8. Gérer la concurrence : plus efficace qu'augmenter les tentatives

Les problèmes de limitation ne se règlent généralement pas par les tentatives, mais par la gouvernance de l'entrée :

  • Une clé dédiée et un plafond de concurrence par service.
  • Découper et décaler les tâches par lots pour éviter le pic de l'heure pile.
  • Lisser avec une file : les échecs vont dans une file différée au lieu de tourner en boucle.
  • Surveiller la part de 429 et la latence P95 ; en cas de hausse, réduire d'abord la concurrence.
  • Prévoir un modèle ou une entrée de secours, en vérifiant la compatibilité des paramètres avant bascule.

Les plafonds de concurrence, de requêtes par minute et de débit de tokens varient selon l'offre et le modèle ; la console et la documentation font foi. Ne copiez pas les chiffres d'autrui : réglez selon vos mesures.

9. Liste à préparer avant de contacter le support

  1. Heure et fuseau de l'incident, caractère soudain ou progressif.
  2. URL de base, chemin d'interface, nom du modèle et méthode d'appel.
  3. Code HTTP, code métier et message d'erreur complet.
  4. Identifiant d'erreur ou de requête ; à défaut, votre trace_id.
  5. Une requête curl minimale reproductible, clé masquée.
  6. Streaming ou non, contexte long ou non, configuration récemment modifiée ou non.
  7. Périmètre d'impact : une clé, un projet ou tous les services.

Avec ces éléments, le support peut localiser directement au lieu d'échanger des allers-retours. Après chaque incident, ajoutez supervision et alertes sans attendre le retour des utilisateurs.

10. Questions fréquentes

Un 429 est-il toujours une limitation de débit ?

Non. Un 429 peut aussi signaler un impayé (1113), un plafond de période (1308, 1310), un modèle absent de l'offre (1311) ou une limitation d'usage équitable (1313). Lisez le code métier avant de choisir entre backoff, recharge et modification de configuration.

Que faire si un 401 persiste avec une nouvelle clé ?

Vérifiez que l'en-tête est bien Authorization: Bearer <clé>, que la variable d'environnement est chargée, que le type de clé correspond à l'interface, que l'URL de base correspond à la clé, et que le reverse proxy ne supprime pas l'en-tête d'authentification.

Faut-il réessayer après un timeout ?

Seulement un nombre limité de fois pour les échecs de connexion et les timeouts de lecture, avec backoff exponentiel. Pour les opérations à effet de bord, vérifiez d'abord si elles ont été exécutées afin d'éviter une double commande ou écriture.

Comment diagnostiquer une rupture du streaming ?

Notez le contenu reçu, le dernier segment et finish_reason, puis distinguez gigue réseau, coupure du proxy et timeout amont. Le client doit gérer reconnexion et déduplication, sans stocker un contenu partiel.

Que faire si le message ne contient qu'un code de statut, sans code métier ?

Conservez le corps et les en-têtes complets, notez trace_id, URL de base, nom du modèle et requête minimale, puis contactez le prestataire. Via une passerelle, transmettez ces informations à la passerelle pour permettre la comparaison avec les journaux amont.

Pour aller plus loin

Créez une clé de test sur ZSQH AI Gateway, entraînez-vous une fois sur 401, 403, 429, 5xx et timeout, puis branchez la supervision de production. Les modèles disponibles et la facturation figurent sur la page Tarifs des modèles.

Articles liés :