Les erreurs de l'API Grok se répartissent en quatre familles : identifiants et droits, chemin et nom de modèle, limitation de débit et quotas, réseau et délais. L'ordre de traitement doit être : d'abord le code HTTP et le type d'erreur, ensuite l'identifiant de requête, et seulement en dernier le prompt ou les paramètres du modèle. Dans l'ordre inverse, on prend facilement un problème de configuration pour un problème de modèle.

Cet article traite séparément les 401, 404, 429 et les délais, avec les causes, les étapes de diagnostic et un code de backoff réutilisable. Les modèles et les prix sont ceux de la page Tarifs des modèles.

Remarque : xAI et Grok sont des marques de leurs détenteurs respectifs. Cet article est fourni à titre technique. Les types d'erreur et le comportement des interfaces peuvent évoluer ; les cas décrits correspondent aux situations courantes d'octobre 2026 et la documentation officielle de xAI fait foi.

1. Regardez d'abord le code de statut, pas le prompt

Code Signification courante Réessayer ?
400 Paramètre, format ou longueur de contexte incorrect Corriger la requête puis réessayer
401 Clé absente, erronée, expirée ou incompatible avec l'adresse Non, corriger d'abord les identifiants
403 Compte ou clé sans droit, ou restriction régionale ou contractuelle Non, vérifier les droits et l'état du compte
404 Chemin incorrect ou nom de modèle inexistant Non, vérifier l'adresse et le nom du modèle
429 Fréquence, concurrence ou tokens au-delà de la limite Réessayer avec un backoff
500 Erreur interne du service en amont Réessayer avec un backoff
502 ou 503 Passerelle ou amont temporairement indisponible Réessayer avec un backoff
504 Délai d'attente de la passerelle vers l'amont Réduire la charge et réessayer

Conservez l'identifiant de requête présent dans la réponse. Pour un diagnostic auprès du prestataire, un identifiant de requête vaut mieux que dix captures d'écran. Les journaux doivent au minimum contenir l'heure, le code de statut, le type d'erreur, le nom du modèle et l'identifiant de requête ; n'y écrivez jamais la clé complète ni de contenu sensible.

2. 401 : vérifier l'en-tête, puis la clé

Un 401 signifie que l'identité n'a pas été validée ; cela n'a rien à voir avec le solde ou les capacités du modèle. Procédez dans cet ordre :

  1. L'en-tête d'authentification est-il bien Authorization: Bearer <Key> ? Le point d'entrée compatible OpenAI de Grok n'utilise pas x-api-key.
  2. La clé comporte-t-elle un espace, un saut de ligne ou des guillemets superflus avant ou après ? C'est le problème le plus fréquent lors d'un copier-coller depuis une messagerie.
  3. La clé et l'URL de base viennent-elles du même fournisseur ? Une clé officielle avec l'adresse de la passerelle, ou l'inverse, échouera.
  4. La clé a-t-elle été révoquée, expirée, ou le projet associé n'a-t-il pas le droit d'appeler ?
  5. La variable d'environnement est-elle réellement chargée ? Affichez seulement les premiers caractères de la clé, jamais la valeur complète dans les journaux.
  6. L'URL de base pointe-t-elle vers le bon environnement, et le chemin est-il /v1/chat/completions ?
export GROK_API_KEY="sk-votre_cle"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Réponds uniquement OK"}],
    "max_tokens": 16
  }'

Un code 200 confirme que la clé, l'adresse et le nom du modèle fonctionnent. Si un 401 persiste, testez la même clé sur un autre point d'entrée : vous distinguerez un problème de clé d'un problème de configuration de passerelle ou de réseau.

3. 404 : vérifier le chemin et le nom du modèle

Un 404 ne vient généralement pas de la clé, mais du fait que « ce que vous demandez n'existe pas ». Quatre causes courantes :

  • L'URL de base contient déjà /v1 et le code l'ajoute une seconde fois, produisant /v1/v1/chat/completions.
  • Le point de terminaison est écrit /completions ou /responses, alors que le point d'entrée courant ne propose que Chat Completions.
  • Le nom du modèle est mal orthographié, ou le compte ou groupe n'a pas activé ce modèle.
  • L'URL de base se termine par une barre oblique, ce qui crée une double barre ou un chemin incorrect après concaténation.

Ordre de diagnostic : envoyez d'abord avec curl une requête sur le chemin standard indiqué dans la documentation officielle, puis copiez le nom du modèle depuis la console ou la page Tarifs des modèles. N'écrivez pas le nom de mémoire et ne reprenez pas directement le nom d'un modèle d'une autre plateforme.

4. 429 : une limitation de débit n'est pas un solde insuffisant

Un 429 indique que la requête dépasse une limite de débit ou de quota. Situations fréquentes :

  • Nombre de requêtes ou de tokens par minute dépassé.
  • Pic de concurrence qui sature le quota en peu de temps.
  • Plusieurs services partagent une même clé et se disputent le quota.
  • Les nouvelles tentatives n'ont pas de backoff et amplifient l'échec, créant une tempête de retries.
  • Une sortie longue consomme beaucoup de tokens de sortie et réduit la marge disponible pour la concurrence.
Symptôme Cause possible Traitement
429 concentrés aux heures de pointe Pic de trafic File d'attente et lissage de l'envoi
429 avec une clé partagée entre services Quota mutualisé Séparer les clés par projet
Aggravation après retry Retries sans backoff Backoff exponentiel avec gigue aléatoire
429 sur les requêtes longues en premier Tokens de sortie élevés Réduire max_tokens ou la concurrence

Regardez d'abord le retry-after de la réponse s'il existe, puis décidez du délai d'attente. Utilisez le type d'erreur du SDK plutôt qu'une correspondance de chaîne sur le message :

import random
import time
from openai import OpenAI, APIStatusError, RateLimitError

client = OpenAI(
    api_key="sk-votre_cle",
    base_url="https://ai.zhongshangqihang.com/v1",
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="grok-4",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, tentative {attempt + 1}, attente de {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, nouvelle tentative dans {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Nombre de tentatives épuisé")

Le retry ne convient qu'aux erreurs transitoires. Pour une opération ayant déjà produit des effets de bord, vérifiez avec une clé d'idempotence ou un contrôle d'état si elle a été exécutée avant de décider de la renvoyer.

5. Délais et erreurs de connexion

Il faut distinguer le délai de connexion du délai de lecture. Un délai de connexion indique généralement un problème de réseau, de DNS ou de proxy ; un délai de lecture peut venir d'une génération longue, d'une réponse en flux interrompue ou d'un délai d'inactivité trop court côté proxy.

Ordre de diagnostic :

  1. Utilisez curl pour relever time_namelookup, time_connect, time_appconnect et time_starttransfer, afin de voir où le temps est consommé.
  2. Vérifiez si le proxy applique un délai de connexion ou d'inactivité trop court.
  3. Pour les sorties longues, passez en flux et lisez au fil de la génération au lieu d'attendre la réponse complète.
  4. Configurez séparément un délai de connexion et un délai de lecture côté client, plutôt qu'un unique délai global très large.
  5. Après un délai dépassé, vérifiez si la requête a déjà été exécutée avant de réessayer, pour éviter une double facturation ou une double écriture.
export GROK_API_KEY="sk-votre_cle"

curl -o /dev/null -s \
  -w "code=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
  --max-time 120 \
  "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4","messages":[{"role":"user","content":"Réponds uniquement OK"}],"max_tokens":8}'

Si le DNS et la connexion sont rapides mais le premier octet lent, le problème vient probablement de la génération ou de l'amont. Si la connexion elle-même expire, vérifiez d'abord la sortie réseau et le proxy, sans modifier le code métier.

6. Tableau récapitulatif du diagnostic

  1. Notez le code de statut, le type d'erreur, l'identifiant de requête, le nom du modèle et l'heure.
  2. Pour 401 et 403, vérifiez les identifiants, l'état du compte et les droits ; pour 404, le chemin et le nom du modèle.
  3. Pour 400, vérifiez les paramètres, la longueur du contexte, le format des images et la taille du corps.
  4. Pour 429, vérifiez le quota, la concurrence, le partage de clé et les tempêtes de retries.
  5. Pour un délai, analysez séparément DNS, connexion, TLS, premier octet et durée totale.
  6. Pour 5xx, appliquez d'abord un backoff, puis contactez le prestataire avec l'identifiant de requête si le problème persiste.
  7. Après chaque incident, complétez la supervision et les alertes au lieu d'attendre le retour des utilisateurs.

Questions fréquentes

Quelle différence entre 429 et un solde insuffisant ?

Un 429 signifie que la requête dépasse une limite de débit ou de quota ; une recharge ne suffit pas forcément. Un solde insuffisant renvoie généralement une erreur liée au quota ou à la facturation. Vérifiez le type d'erreur et la facturation avant de décider s'il faut attendre, réduire la concurrence ou recharger.

Pourquoi les 429 augmentent-ils après l'ajout de retries ?

Il manque peut-être un backoff, la concurrence est trop élevée, ou plusieurs services partagent une clé. Des retries à intervalle fixe transforment une petite limitation en tempête. Utilisez un backoff exponentiel avec gigue aléatoire et fixez un nombre maximal de tentatives.

Le modèle existe, pourquoi un 404 ?

Vérifiez d'abord si l'URL de base concatène deux fois /v1, puis si le point de terminaison est bien /chat/completions. Si le chemin est correct, le compte ou le groupe n'a peut-être pas activé le modèle, ou la casse ou le suffixe de version du nom diffère.

Peut-on renvoyer directement une requête après un délai dépassé ?

Il faut d'abord déterminer si la requête a été exécutée. Une lecture seule peut généralement être réessayée ; une opération avec écriture, facturation ou effet externe doit utiliser une clé d'idempotence ou vérifier l'état avant d'être renvoyée.

Comment distinguer une erreur de passerelle d'une erreur d'amont ?

Regardez le type d'erreur et l'identifiant de requête, puis envoyez la même requête au point d'entrée de la passerelle et au point d'entrée officiel. Vous distinguerez rapidement un problème de clé, de réseau, de configuration de passerelle ou de service amont.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, exercez une fois les cas 401, 404, 429 et délai, puis branchez la supervision de production. La disponibilité des modèles et les prix sont ceux de la page Tarifs des modèles.

Articles liés :