Les erreurs de l'API MiniMax se répartissent en gros en quatre couches : code de statut HTTP, code métier dans le corps de réponse, délai d'attente de la couche transport et anomalie du service amont. Diagnostiquez d'abord par couche, puis localisez, au lieu de modifier immédiatement le prompt ou de changer de modèle. Beaucoup de problèmes attribués au « modèle » se révèlent être une clé mal configurée, des adresses mélangées ou un délai trop court.

Cet article détaille 401, 403, 404, 429, 5xx et les délais, avec causes, ordre de diagnostic et code de gestion réutilisable. Les noms de modèles, prix et quotas font foi dans la documentation officielle et sur la page Tarifs des modèles.

Remarque : MiniMax est une marque de son détenteur. Les codes d'erreur, les paliers de limitation et le comportement des interfaces peuvent évoluer ; cet article décrit les cas courants d'octobre 2026 et la documentation officielle de MiniMax fait foi.

1. Séparer d'abord statut, code métier et délai

La documentation officielle des codes d'erreur de MiniMax liste séparément les codes métier et demande de fournir le trace_id de l'en-tête de réponse lors d'un signalement. La documentation de limitation impose trois dimensions : RPM, TPM et nombre de tâches concurrentes. Le diagnostic doit regarder à la fois la couche HTTP et la couche métier : certaines interfaces natives peuvent renvoyer un HTTP 200 avec l'erreur dans base_resp du corps de réponse ; l'entrée compatible OpenAI exprime généralement l'erreur par le statut HTTP. Enregistrez les deux couches pour ne rien manquer.

Symptôme Signification courante À vérifier en priorité Traitement
401, 1004, 2049 Échec d'authentification ou clé invalide Clé, en-tête Bearer, adresse correspondante Nouvelle clé et requête minimale
403 Droits, état du compte ou restriction d'entrée Droits du modèle, vérification d'identité, quota côté passerelle Comparer console et corps de réponse
404 Chemin ou modèle inexistant URL de base, /v1, modèle retiré Consulter la liste officielle des modèles
400, 2013, 1039 Paramètre invalide ou jeton dépassé thinking, temperature, max_tokens Resserrer les paramètres selon la documentation
429, 1002, 2045, 1041, 2056 Limitation, concurrence ou fenêtre de forfait RPM, TPM, clés partagées, pic de trafic Backoff, file d'attente, séparation des clés
1008 Solde insuffisant Solde, quota d'abonnement Recharger ou changer de mode de facturation
Délai, 1001 Délai de connexion ou de lecture Réseau, proxy, sortie longue, streaming Délais réglés par couche
5xx, 1024, 1033 Anomalie du service amont État du service, requête rejouable Backoff avec plafond

Journalisez au minimum l'horodatage, le statut, le code métier, le nom du modèle, la durée et le trace_id. N'écrivez jamais la clé complète ni le texte utilisateur intégral dans les journaux.

2. 401 et 403 : réparer l'authentification avant les droits

401 signifie que l'identité n'est pas vérifiée, généralement indépendamment des capacités du modèle. Suivez cet ordre :

  • L'en-tête est-il Authorization: Bearer <key> et non un schéma personnalisé ?
  • La clé contient-elle des espaces, retours à la ligne ou guillemets avant ou après ? Les copies depuis une fenêtre de chat en ajoutent facilement.
  • Les variables d'environnement sont-elles réellement chargées ? Affichez seulement le préfixe pour vérifier.
  • La clé a-t-elle été supprimée, renouvelée ou désactivée ?
  • L'URL de base et la clé appartiennent-elles à la même plateforme ? Une clé officielle sur l'adresse d'une passerelle renvoie 401.
  • Un reverse proxy écarte-t-il ou remplace-t-il l'en-tête Authorization ?
  • Mélangez-vous une clé d'abonnement M Plan et une clé de paiement à l'usage ? La documentation officielle indique qu'elles sont indépendantes et que leurs quotas ne se substituent pas.

403 renvoie plutôt aux droits ou à l'état du compte : modèle activé ou non, état de vérification, droit d'usage du modèle sur l'entrée utilisée, quota ou contrôle des risques côté passerelle. La sémantique de 403 peut varier selon l'entrée : lisez d'abord le message d'erreur et la marque de source dans le corps. Si la même requête passe par l'entrée officielle mais renvoie 403 via la passerelle, vérifiez d'abord la configuration et le quota de la passerelle.

3. 404 : URL de base et nom de modèle sont les erreurs les plus fréquentes

Un 404 ne signifie pas que « l'interface est tombée », mais que la requête vise un chemin ou un modèle inexistant. Causes courantes :

  • URL de base d'un autre fournisseur, ou /v1 en trop ou manquant.
  • Le SDK ajoute automatiquement /chat/completions, et le chemin écrit à la main l'ajoute une seconde fois.
  • Nom de modèle d'une ancienne version retirée, ou casse et suffixe incohérents.
  • Mélange d'adresses officielles et de passerelle, avec des règles de chemin différentes.
  • Règle de réécriture du reverse proxy qui casse le chemin.

La liste officielle des modèles MiniMax montre que les modèles texte historiques M2.5/M2.7 sont en cours de retrait : service arrêté pour les nouveaux utilisateurs depuis le 19 octobre 2026 et retrait complet prévu le 18 novembre 2026. Les modèles texte actuellement documentés sont MiniMax-M3 et MiniMax-M3.1-Flash. Continuer avec un ancien nom peut produire un 404 ou une erreur métier. Vérifiez le nom dans la liste officielle et sur la page de tarifs avant de migrer.

4. 429 : une limitation n'est pas un solde insuffisant

429 signifie que la requête dépasse la limite de débit, de concurrence ou de quota. La documentation officielle de MiniMax limite selon le RPM (requêtes par minute), le TPM (jetons d'entrée et de sortie par minute) et le nombre de tâches concurrentes ; compte principal et sous-comptes partagent le quota. Les paliers par défaut indiqués pour M3/M3.1-Flash sont de 20 RPM pour les utilisateurs gratuits et 200 RPM pour les comptes rechargés, avec respectivement 1 million et 10 millions de TPM ; la console fait foi.

Scénarios de déclenchement courants :

  • Plusieurs services partagent une clé et se disputent le quota.
  • Des tâches par lots démarrent toutes à l'heure pile, créant un pic de trafic.
  • Les nouvelles tentatives n'ont pas de backoff et amplifient l'échec en tempête.
  • Les sorties longues ou les tâches de raisonnement occupent les ressources et réduisent la concurrence disponible.
  • La fenêtre du forfait expire et déclenche la limite des ressources M Plan.

Traitements correspondants : séparer les clés par projet ; placer les tâches par lots dans une file pour lisser l'envoi ; plafonner les nouvelles tentatives avec backoff exponentiel et gigue ; limiter séparément les sorties longues ; respecter en priorité l'en-tête Retry-After s'il est présent. En recevant un 429, n'augmentez pas la concurrence : lissez d'abord les requêtes.

5. Délais et 5xx : distinguer connexion, premier jeton et lecture

Un délai ne signifie pas que le service est indisponible ; localisez d'abord le segment bloqué :

  • Délai de connexion : DNS, sortie réseau ou proxy injoignable ; vérifiez réseau et proxy.
  • Premier jeton lent : file amont ou prompt trop long ; raccourcissez l'entrée, décalez l'appel ou utilisez un modèle plus léger.
  • Délai de lecture : sortie trop longue ou réflexion longue du modèle de raisonnement ; augmentez le délai de lecture et limitez la sortie.
  • Flux interrompu : gigue réseau ou coupure du proxy ; le client doit gérer la reconnexion et la déduplication.
  • Délai de tâche asynchrone : pour la vidéo et la voix, distinguez « tâche en file » et « requête expirée » ; interrogez par task_id sans soumettre à nouveau.

Les 5xx et les codes métier 1000, 1024 et 1033 indiquent généralement une anomalie ou une surcharge amont. Ces erreurs se prêtent au backoff, mais avec un plafond. Pour les opérations à effet de bord, utilisez une clé d'idempotence ou une interrogation d'état pour vérifier si l'action a déjà eu lieu. Les liens de téléchargement de la voix asynchrone ont une durée de validité (9 heures selon la documentation actuelle) et doivent être obtenus à nouveau après expiration.

6. Code de gestion des erreurs : backoff, trace_id et journaux

import logging
import os
import random
import time

import httpx
from openai import (
    APITimeoutError,
    APIStatusError,
    AuthenticationError,
    OpenAI,
    RateLimitError,
)

log = logging.getLogger("minimax")
client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # désactive les réessais du SDK, gérés ci-dessous
)

def trace_id(exc: Exception) -> str:
    response = getattr(exc, "response", None)
    headers = getattr(response, "headers", {}) or {}
    return headers.get("trace_id") or headers.get("x-request-id") or "-"

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["MINIMAX_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            log.error("échec d'authentification status=%s trace_id=%s",
                      exc.status_code, trace_id(exc))
            raise
        except RateLimitError as exc:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            log.warning("limitation attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APITimeoutError as exc:
            wait = min(2 ** attempt, 15) + random.uniform(0, 1)
            log.warning("délai dépassé attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 30) + random.uniform(0, 1)
                log.warning("erreur amont status=%s attempt=%s wait=%.1fs trace_id=%s",
                            exc.status_code, attempt + 1, wait, trace_id(exc))
                time.sleep(wait)
                continue
            log.error("erreur client status=%s detail=%s trace_id=%s",
                      exc.status_code, exc, trace_id(exc))
            raise
    raise RuntimeError("tentatives épuisées ; contactez le fournisseur avec le trace_id")

print(ask("Expliquez en une phrase ce qu'est la limitation d'une API"))

Ce code fait quatre choses : distinguer les erreurs rejouables des autres, appliquer un backoff exponentiel avec gigue, écrire le trace_id dans les journaux et traiter les 5xx séparément. Il ne remplace pas une conception idempotente : une requête à effet de bord doit d'abord vérifier l'état.

7. Journaux et supervision : les champs minimaux

  • Horodatage et projet : localiser les pics et le périmètre d'impact.
  • Statut HTTP et code métier : distinguer authentification, limitation, paramètres et erreurs amont.
  • trace_id ou x-request-id : la preuve clé pour le diagnostic côté fournisseur.
  • Adresse d'interface et nom de modèle : savoir si le problème apparaît après un changement de modèle ou d'entrée.
  • Jetons d'entrée et de sortie : analyser coûts et requêtes longues.
  • Durée, nombre de tentatives et concurrence : détecter la latence de queue et les tempêtes de réessais.
  • Alias de clé : statistiques par projet, sans journaliser la valeur en clair.

La supervision doit au minimum compter chaque heure les 401, 403, 404, 429, délais et 5xx. Quand le taux d'erreur bondit, 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, changer de canal ou revenir à une version précédente.

8. Checklist avant de contacter le support

  1. Heure, fuseau, durée et interfaces concernées.
  2. Statut HTTP, code métier et message complet, après anonymisation des contenus sensibles.
  3. trace_id de l'en-tête de réponse, et x-request-id éventuellement ajouté par la passerelle.
  4. Adresse d'interface, nom de modèle, version du SDK et paramètres de requête.
  5. Une commande curl minimale reproductible, sans données métier ni données personnelles.
  6. Connexion directe ou passerelle, clé à l'usage ou clé M Plan.
  7. Concurrence, RPM/TPM, nombre de tentatives et présence d'un pic de trafic sur la même période.
  8. Changement récent de modèle, mise à jour du SDK, modification du proxy ou de la passerelle.
  9. Pour un 1008, une capture du solde ou de l'état du forfait, également anonymisée.

Rassembler ces éléments dans un seul message accélère beaucoup le traitement par rapport à un simple « ça renvoie une erreur ». Le fournisseur demande généralement d'abord le trace_id et la fenêtre temporelle.

Questions fréquentes

Un 429 signifie-t-il un solde insuffisant ?

Non. 429 indique un dépassement de la limite de débit, de concurrence ou de quota ; le solde insuffisant correspond généralement au code métier 1008. Vérifiez d'abord la concurrence, les clés partagées et les pics de trafic.

Pourquoi une erreur avec un HTTP 200 ?

Certaines interfaces natives MiniMax expriment l'erreur métier via base_resp.status_code dans le corps, alors que la couche HTTP reste à 200. Avec ces interfaces, le code doit analyser le corps et pas seulement le statut ; l'entrée compatible OpenAI renvoie généralement directement un code HTTP d'erreur.

Où récupérer le trace_id ?

La documentation officielle des codes d'erreur indique de lire trace_id dans l'en-tête de réponse. Via une passerelle, celle-ci peut ajouter un x-request-id : journalisez les deux.

Peut-on réessayer indéfiniment après un délai dépassé ?

Non. Les réessais doivent avoir une limite, un backoff et une alerte ; un délai peut aussi signifier que la requête a déjà été exécutée en amont. Pour une opération à effet de bord, vérifiez l'état avant de renvoyer.

Que faire après un 404 consécutif à un changement de modèle ?

Vérifiez d'abord si le nom du modèle a été retiré, puis si l'URL de base contient un /v1 en trop ou manquant. Les modèles texte historiques de MiniMax sont retirés par vagues ; ne présumez pas qu'un ancien nom reste disponible et référez-vous à la liste officielle et à la page de tarifs.

Pour aller plus loin

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

Lectures associées :