La plupart des erreurs de l'API Mistral ne viennent pas des capacités du modèle, mais des identifiants, du chemin, des paramètres, de la limitation de débit ou du réseau. L'ordre de diagnostic doit être le suivant : d'abord le code de statut HTTP et le type d'erreur, ensuite le request ID présent dans la réponse et une reproduction minimale, et seulement en dernier lieu l'ajustement du prompt ou le changement de modèle. Inverser cet ordre conduit facilement à prendre une erreur de configuration pour une faiblesse du modèle.
Cet article détaille les cas 401, 403, 404, 422, 429, 5xx et les délais d'attente, avec du code de nouvelle tentative, de la gouvernance de concurrence, les champs de journalisation et une liste d'informations à fournir au support. Les quotas, les messages d'erreur et le comportement des interfaces peuvent évoluer : la documentation et la console officielles de Mistral font foi.
Note : Mistral est une marque de son titulaire. Cet article est purement technique ; les codes d'erreur, les règles de limitation et le comportement des interfaces peuvent changer selon les versions. La documentation et la console officielles restent la référence.
1. Regarder le code de statut avant de toucher au prompt
| Statut ou symptôme | Signification courante | Cause typique | Ordre de traitement |
|---|---|---|---|
| 401 | Authentification non validée | Clé absente, mal formée ou expirée | Corriger d'abord les identifiants |
| 403 | Permissions insuffisantes | Modèle non activé, rôle d'espace insuffisant, restriction régionale | Vérifier compte et permissions |
| 404 | Chemin ou modèle inexistant | URL de base erronée, chemin dupliqué, modèle retiré | Vérifier l'adresse et le nom du modèle |
| 422 | Requête syntaxiquement valide mais sémantiquement invalide | Champ manquant, type incorrect, paramètre non pris en charge | Lire le détail et corriger les paramètres |
| 429 | Limitation de débit ou quota atteint | Pic de concurrence, clé partagée, tempête de retries | Backoff, réduire la concurrence |
| 5xx | Anomalie côté amont | Surcharge, erreur de passerelle, incident temporaire | Retries limités, changer de canal |
| Délai d'attente | Timeout de connexion ou de lecture | Réseau instable, sortie trop longue, timeout d'inactivité du proxy | Localiser par couche |
Le journal doit au minimum contenir l'heure, le code de statut, le type d'erreur, le nom du modèle, la durée et le request ID. Ne journalisez jamais la clé complète ni le texte original de l'utilisateur.
2. 401 et 403 : authentification et permissions
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. Procédez dans cet ordre :
- Vérifier que l'en-tête est bien
Authorization: Bearer <key>, et non un champ personnalisé ou un ancien mécanisme. - Vérifier l'absence d'espaces, de retours à la ligne ou de guillemets superflus autour de la clé ; une copie depuis une fenêtre de chat en introduit facilement.
- Vérifier que la variable d'environnement est réellement chargée ; afficher uniquement le préfixe pour le confirmer, jamais la clé entière.
- Vérifier que la clé n'a pas été supprimée, renouvelée ou désactivée, et que l'environnement de test n'utilise pas une clé de production.
- Vérifier que l'URL de base et la clé appartiennent à la même plateforme : une clé de la plateforme A envoyée à la plateforme B renvoie directement 401.
- Vérifier que le proxy inverse ou le SDK ne remplace pas ou ne supprime pas l'en-tête
Authorization.
Un 403 signifie « identité reconnue, mais pas de permission ». Les causes courantes sont : le compte ou l'espace de travail n'a pas le droit d'appeler ce modèle, le rôle est insuffisant, le modèle n'est pas ouvert dans la région courante, ou la requête vise une interface non activée. Consultez d'abord la liste des modèles et les permissions des membres dans la console, puis appelez avec la même clé un modèle dont vous savez qu'il fonctionne, pour comparer.
3. 404 et 422 : adresse, nom de modèle et paramètres
Un 404 ne signifie généralement pas que l'interface est tombée : la requête vise un chemin ou un modèle inexistant. Les causes fréquentes incluent une URL de base erronée, un /v1 en trop ou manquant, un SDK qui ajoute automatiquement le chemin alors que le code le concatène une seconde fois, un ancien nom de modèle retiré, ou une passerelle sans route configurée. Envoyez d'abord une requête minimale à l'adresse complète, lisez le message d'erreur du corps de réponse, puis comparez un par un avec la liste des modèles de la console.
Un 422 indique que la requête est bien formée mais sémantiquement invalide : champ obligatoire manquant, type incorrect, messages vide, max_tokens hors limites, paramètre non pris en charge par le modèle courant, ou structure JSON corrompue. Le corps de réponse indique généralement le champ concerné et la raison ; lisez detail ou error et corrigez en conséquence, sans relancer à l'aveugle.
4. 429 : limitation de débit, concurrence et tempête de retries
Un 429 signifie que la requête dépasse une limite de débit, de concurrence ou de quota ; cela ne veut pas dire que le solde est insuffisant. Scénarios déclencheurs fréquents :
- Plusieurs services partagent une même clé et se disputent le quota.
- Des tâches par lots démarrent toutes à la même heure, créant un pic de trafic.
- Les retries n'ont pas de backoff : plus ça échoue, plus ça renvoie, jusqu'à la tempête de retries.
- Des sorties longues ou des requêtes en streaming occupent les connexions plus longtemps, réduisant la place disponible pour la concurrence.
- Les environnements de test, de préproduction et de production ne sont pas séparés, et le trafic de test sature le quota de production.
Commencez par vérifier si la réponse contient un indicateur de limitation comme Retry-After ; si oui, attendez la durée indiquée. Sinon, utilisez un backoff exponentiel avec une gigue aléatoire. Réduisez en parallèle la concurrence, ajoutez une file d'attente et un limiteur à jetons pour les tâches par lots, et fixez des limites par modèle, par clé et par environnement. Ne traitez pas les retries comme une extension de capacité : ils absorbent les micro-incidents, pas une insuffisance durable.
5. 5xx et délais d'attente : amont, réseau et streaming
Les 5xx incluent 500, 502, 503 et 504 ; ils peuvent venir d'une surcharge amont, d'un échec de transfert par la passerelle ou d'un incident temporaire. Commencez par délimiter l'impact : tous les modèles échouent-ils, ou seulement un modèle, une région ou une liaison ? Un 5xx bref peut être retenté un nombre limité de fois ; un 5xx persistant impose de réduire la concurrence, de basculer sur un canal de secours et de conserver le request ID pour contacter la plateforme.
Les délais d'attente se divisent en timeout de connexion, timeout de lecture et timeout d'inactivité en streaming. Le timeout de connexion relève souvent du réseau, du DNS ou du proxy ; le timeout de lecture apparaît fréquemment sur les sorties longues, les raisonnements complexes et les files d'attente amont ; en streaming, le timeout d'inactivité du proxy peut couper la connexion. Le client doit définir explicitement les timeouts de connexion et de lecture, et en streaming prévoir un timeout d'inactivité et une stratégie de reconnexion. Pour les requêtes à effet de bord, ne renvoyez pas directement après un timeout : vérifiez d'abord si l'amont a déjà exécuté l'opération.
6. Request ID et journaux : la base du diagnostic
Le request ID est le point d'ancrage du diagnostic entre équipes. Les en-têtes de réponse ou le corps d'erreur contiennent généralement un identifiant de requête, souvent sous la forme x-request-id. En direct comme via une passerelle, enregistrez-le et associez-le au numéro de dossier métier dans les journaux.
Un journal utile contient au minimum : l'heure, le request ID, le code de statut, le type d'erreur, le nom du modèle, le nombre de tokens d'entrée et de sortie, la durée, le nombre de retries, le mode streaming et le canal amont. Le contenu utilisateur doit être anonymisé ou résumé ; la clé ne doit apparaître que par son préfixe. Une capture d'erreur sans request ID rend très difficile la localisation de la requête par le support.
7. Retries et backoff : ce qui peut être retenté et comment
Un retry doit remplir trois conditions : l'erreur est récupérable, la requête est rejouable, et le nombre de tentatives est borné. Ne retentez pas les 401, 403, 404 et 422 : ce sont des problèmes de configuration ou de paramètres, et réessayer ne fait que perdre du temps. Les 429, 5xx et timeouts peuvent être retentés de façon bornée, en respectant en priorité Retry-After.
L'exemple ci-dessous combine les statuts retentables, le backoff exponentiel, la gigue aléatoire et l'enregistrement du request ID. En production, ajoutez un disjoncteur, la remontée de métriques et une décision d'idempotence métier avant tout renvoi.
import os
import random
import time
import requests
API_KEY = os.environ["MISTRAL_API_KEY"]
URL = "https://api.mistral.ai/v1/chat/completions"
RETRY_STATUS = {429, 500, 502, 503, 504}
def wait_seconds(resp, attempt):
value = resp.headers.get("Retry-After") if resp is not None else None
if value:
try:
return min(float(value), 60.0)
except ValueError:
pass
return min(2 ** attempt + random.random(), 30.0)
def chat(payload, max_retries=4):
last_error = None
for attempt in range(max_retries + 1):
try:
resp = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 60), # connexion 5 s, lecture 60 s
)
except requests.Timeout as exc:
last_error = exc
if attempt == max_retries:
break
time.sleep(wait_seconds(None, attempt))
continue
request_id = resp.headers.get("x-request-id", "unknown")
if resp.status_code == 200:
return resp.json()
if resp.status_code in RETRY_STATUS:
last_error = RuntimeError(
f"HTTP {resp.status_code}, request_id={request_id}"
)
if attempt == max_retries:
break
time.sleep(wait_seconds(resp, attempt))
continue
# 401/403/404/422 : inutile de réessayer, il faut corriger la configuration ou les paramètres
raise RuntimeError(
f"HTTP {resp.status_code}, request_id={request_id}, "
f"body={resp.text[:500]}"
)
raise RuntimeError(f"retry exhausted: {last_error}")
Au-delà des retries, gérez la concurrence : un sémaphore par modèle, une file pour les tâches par lots, des clés distinctes par environnement et une alerte sur la proportion de 429. La limitation de débit doit être traitée comme un problème de capacité, pas comme une erreur accidentelle.
8. Liste d'informations pour un ticket de support
Avant de contacter le support, rassemblez les éléments suivants ; cela raccourcit nettement le diagnostic :
- L'heure et la plage concernées, avec le fuseau horaire, en précisant si l'échec est continu ou intermittent.
- Le request ID complet, le code de statut et le corps d'erreur, en version anonymisée.
- L'adresse de la requête, le nom du modèle, le mode streaming, l'usage éventuel d'outils ou de sorties structurées.
- Une requête minimale reproductible, débarrassée des champs métier inutiles mais conservant les paramètres nécessaires.
- Le périmètre d'impact : nombre d'utilisateurs, régions, réseaux, et échec de tous les modèles ou non.
- Les changements récents : rotation de clé, mise à jour de modèle, modification du proxy ou de la passerelle.
- Les vérifications déjà effectuées et leurs résultats : changement de clé, de modèle, de réseau, réduction de concurrence.
Questions fréquentes
Un 401 persiste après avoir changé de clé, que faire ?
Vérifiez d'abord que la nouvelle clé appartient bien à la plateforme correspondant à l'URL de base, puis que la variable d'environnement est réellement chargée et que le proxy transmet l'en-tête Authorization. Une requête minimale envoyée séparément à l'entrée officielle et à l'entrée de la passerelle permet de distinguer rapidement un problème de clé d'un problème de liaison.
Un 429 signifie-t-il un solde insuffisant ?
Non. Un 429 indique un dépassement de débit, de concurrence ou de quota ; un solde insuffisant renvoie généralement une autre erreur ou l'explique dans le corps de réponse. Vérifiez d'abord la concurrence, le partage de clé et la stratégie de retry, puis l'état du compte.
Quelle différence entre 422 et 400 ?
Les deux peuvent signaler un problème de paramètres, mais 422 insiste sur une requête bien formée mais sémantiquement invalide, par exemple un type de champ incorrect ou un champ obligatoire manquant. Dans la pratique, fiez-vous aux indications de champ du corps de réponse plutôt qu'au seul code de statut.
Peut-on renvoyer directement après un timeout ?
Cela dépend des effets de bord de la requête. Une simple lecture peut être retentée de façon bornée ; pour une commande, un débit ou l'envoi d'un message, vérifiez d'abord si l'amont a exécuté l'opération, ou utilisez une clé d'idempotence. Un timeout signifie seulement que le client n'a pas reçu de résultat, pas que l'amont n'a rien traité.
Que préparer avant d'ouvrir un ticket ?
La plage horaire, le request ID, le code de statut, le corps d'erreur, le nom du modèle, une reproduction minimale et le périmètre d'impact. Ajoutez les changements récents et les vérifications déjà effectuées : le support pourra localiser plus vite la liaison concernée.
Étape suivante
Créez d'abord une clé de test sur ZSQH AI Gateway, puis exercez séparément les cas 401, 422, 429 et timeout avant de brancher la supervision de production. La disponibilité des modèles et les règles de facturation sont indiquées sur la page Tarifs.
