Les erreurs de l'API Moonshot ne se lisent pas uniquement dans le code de statut. Un même 429 peut signaler une surcharge de cluster, une limitation de débit du compte ou un solde insuffisant ; un même 401 peut venir d'une clé mal copiée ou d'un mélange entre le site chinois et le site international. En 2026, la migration des points d'entrée et le retrait d'anciens modèles ont en outre fait augmenter nettement les 404.

Cet article suit l'ordre « localiser, classer, corriger » et détaille cinq familles de problèmes : 401, 404, 429, contexte trop long et timeouts. Il fournit un code de nouvelle tentative réutilisable 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 : Moonshot et Kimi sont des marques de leurs détenteurs respectifs. Les types d'erreur, les paliers de limitation et les dates de retrait peuvent évoluer ; cet article s'appuie sur la documentation publique et les cas courants d'octobre 2026, la documentation du fournisseur faisant foi.

1. Fixer d'abord trois champs

Pour diagnostiquer, commencez par collecter trois éléments : le code de statut HTTP, error.type et l'identifiant de requête. La réponse d'erreur de Moonshot contient généralement error.message et error.type, le format exact dépendant de l'interface en cours. L'identifiant de requête peut apparaître dans le corps de l'erreur, dans les en-têtes de réponse ou dans les journaux de la console ; selon les versions, l'emplacement change, ne supposez pas une source unique.

Le journal doit au minimum contenir : l'heure avec fuseau, le code de statut, error.type, le nom du modèle, le site auquel appartient l'URL de base, l'usage ou non du streaming, la version du SDK, le nombre de tentatives, usage et l'identifiant de requête. N'enregistrez jamais la clé complète ni un prompt contenant des données sensibles.

Avec ces trois éléments, vous pouvez déterminer si le problème vient de la configuration, du compte ou du serveur. Les sections suivantes détaillent chaque famille.

2. 401 : vérifier le site avant la clé

Moonshot distingue un site chinois et un site international. Le site chinois utilise platform.kimi.com et l'interface https://api.moonshot.cn/v1 ; le site international utilise platform.kimi.ai et l'interface https://api.moonshot.ai/v1. Les comptes, soldes et clés des deux sites sont totalement indépendants : une clé du site chinois envoyée à l'adresse internationale renvoie un 401 invalid_authentication_error.

Procédez dans cet ordre :

  1. Vérifiez que la clé provient bien du site correspondant à l'URL de base actuelle, et non de l'autre site ou d'un autre compte.
  2. Vérifiez que vous ne mélangez pas une clé de la plateforme ouverte avec une clé d'un autre produit comme Kimi Code : elles ne sont pas interchangeables.
  3. Vérifiez que l'en-tête est bien Authorization: Bearer <clé>, sans espace, saut de ligne ni guillemet autour de la valeur.
  4. Vérifiez que la variable d'environnement est réellement chargée ; afficher les premiers caractères de la clé suffit à le confirmer.
  5. Vérifiez que la clé n'a pas été supprimée, renouvelée, ou que les droits du projet n'ont pas été révoqués.
  6. Vérifiez qu'un ancien proxy, une ancienne variable ou un outil de routage local ne subsiste pas et ne écrase pas la requête actuelle.

Côté types d'erreur, invalid_authentication_error désigne le plus souvent un format de clé incorrect ou un site incompatible, tandis que incorrect_api_key_error désigne le plus souvent une clé absente ou erronée. Dans les deux cas, corrigez d'abord les identifiants, sans relancer immédiatement la requête.

3. 404 : le plus souvent un modèle retiré, pas une interface disparue

En 2026, la source de 404 la plus facile à négliger est le cycle de vie des modèles. La page officielle des modèles recense notamment :

  • toute la série moonshot-v1, dont moonshot-v1-8k, -32k, -128k, -auto et la préversion visuelle, retirée le 31 août 2026, avec migration recommandée vers kimi-k3 ;
  • la série kimi-k2, dont kimi-k2-0905-preview, kimi-k2-0711-preview, kimi-k2-turbo-preview et la version de raisonnement, retirée le 25 mai 2026 ;
  • kimi-latest, retiré le 28 janvier 2026, et kimi-thinking-preview, retiré le 11 novembre 2025.

Autres causes fréquentes de 404 :

  • le SDK OpenAI n'a pas de base_url défini et la requête part vers l'adresse OpenAI par défaut, qui ne connaît pas le modèle ;
  • le nom du modèle est mal orthographié, ou le palier du compte n'a pas accès à ce modèle ;
  • le chemin contient un /v1 en trop ou manquant, ou le client concatène l'URL de base avec un chemin complet ;
  • les noms de modèles disponibles diffèrent entre le site chinois et le site international.

Interrogez la liste des modèles avec la même clé pour voir ce que le compte peut réellement utiliser :

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

Ne devinez pas un nom absent de cette liste. Si la liste répond mais que l'interface de chat renvoie encore 404, concentrez-vous sur la construction du chemin et la configuration du client.

4. 429 : trois types, trois traitements différents

Le 429 est l'erreur la plus souvent mal interprétée. Regardez d'abord error.type :

error.type Signification Nouvelle tentative Traitement
engine_overloaded_error Cluster surchargé, capacité tendue Oui Backoff selon Retry-After, réduire la concurrence
rate_limit_reached_error Concurrence, RPM, TPM ou TPD de l'organisation dépassés Partiellement Ralentir, attendre, augmenter le palier du compte
exceeded_current_quota_error Impayé, solde insuffisant, bon expiré Non Vérifier le solde et recharger

Les paliers de Moonshot vont de Tier0 à Tier5 selon le montant cumulé rechargé ; les bons offerts à l'achat n'entrent généralement pas dans ce cumul. Un palier contraint à la fois la concurrence, les requêtes par minute, les tokens par minute et les tokens par jour : les petits paliers peuvent n'autoriser que quelques requêtes simultanées, les plus élevés plusieurs centaines ; le RPM va de quelques unités à plusieurs centaines, le TPM de quelques centaines de milliers à plusieurs millions. Tier0 impose aussi un plafond quotidien de tokens, généralement réinitialisé le lendemain.

Quelques pièges courants :

  • le SDK OpenAI réessaie automatiquement les 408, 409, 429 et 5xx, jusqu'à trois tentatives au total. Sur un petit palier, un échec peut être amplifié en plusieurs requêtes et épuiser rapidement le RPM. En production, fixez explicitement max_retries ;
  • les outils comme la recherche web ont leur propre limite QPS, calculée séparément du RPM et du TPM de l'interface de chat ; un dépassement renvoie aussi un 429 ;
  • une requête interrompue par un 429 n'est généralement pas facturée, mais une nouvelle tentative réussie l'est normalement ; ne bouclez pas indéfiniment au motif que « ce n'est pas facturé » ;
  • si les limites ne correspondent pas à votre palier, vérifiez d'abord que vous n'utilisez pas la clé d'un autre compte.

5. 400 : contexte trop long et paramètres invalides

Un contexte trop long renvoie généralement un 400 invalid_request_error, avec un message indiquant un dépassement de tokens en entrée. Attention : le critère est la somme « entrée + plafond de sortie » comparée à la fenêtre du modèle, pas la seule entrée.

Déclencheurs fréquents :

  • un historique qui grandit sans limite, sans jamais être tronqué ;
  • un document entier injecté dans un contexte de 1M, avec en plus un plafond de sortie très élevé ;
  • un fichier de plus de 100 Mo envoyé à l'interface fichiers, un fichier vide, ou une valeur de purpose hors liste ;
  • une sortie bloquée par content_filter, un filtre qui peut aussi se déclencher sur la sortie du modèle et pas seulement sur l'entrée.

L'ordre de traitement : estimez d'abord les tokens d'entrée, puis réservez de la place pour la sortie ; résumez les documents longs par segments en conservant les références ; appliquez une fenêtre glissante aux conversations multi-tours ; utilisez les appels d'outils pour les sorties structurées afin de réduire le texte inutile.

Par ailleurs, finish_reason=length n'est pas une erreur : la sortie a simplement atteint son plafond. Pour un résultat plus long, découpez la requête ou utilisez la reprise, sans porter le plafond au-delà de ce que le modèle autorise.

6. Timeouts, 499 et streaming

La passerelle de Moonshot impose une limite d'attente aux requêtes non streamées ; la documentation mentionne un 504 possible après 900 secondes. La génération de textes longs, l'analyse de documents volumineux et les agents de code y sont les plus exposés.

Traitez dans cet ordre :

  1. Passez du non-streaming au streaming avec stream=True, pour que la connexion continue de recevoir des données.
  2. Réglez un timeout de connexion court et un timeout de lecture adapté à la durée maximale de génération, sans reprendre les valeurs par défaut du SDK.
  3. Vérifiez que le proxy d'entreprise, la passerelle et les outils de routage locaux ne coupent pas la connexion trop tôt ; ce type d'interruption peut apparaître comme un 499 client_closed_request.
  4. Limitez la longueur générée par requête via le plafond de sortie et découpez les tâches trop longues.
  5. En streaming, surveillez la latence du premier token ; une hausse soudaine du TTFT indique souvent une congestion amont ou un prompt qui s'allonge.
  6. Journalisez l'identifiant de requête et la durée de chaque timeout, pour distinguer un modèle lent, un réseau lent et un proxy lent.

Le streaming ne réduit pas le prix unitaire, mais il évite la consommation répétée d'un « attendre le timeout puis réessayer ». Ne conservez pas un timeout de lecture court en streaming, sinon le client coupera lui-même une génération pourtant normale.

7. Comment écrire les nouvelles tentatives et le backoff

Les nouvelles tentatives ne conviennent qu'aux erreurs transitoires. Ne réessayez pas automatiquement après un 401, un 403, un 404, un blocage de sécurité de contenu ou un solde insuffisant ; pour un 429, classez d'abord le type ; pour un 5xx, appliquez un backoff. Pour les opérations ayant déjà produit un effet de bord, vérifiez avec une clé d'idempotence ou une requête d'état si l'action a été exécutée.

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

client = OpenAI(
    api_key="votre_clé",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,  # désactive les tentatives automatiques du SDK
)

RETRYABLE_TYPES = {"engine_overloaded_error", "server_error",
                   "server_unavailable", "client_closed_request"}

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k3",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("Solde ou quota insuffisant, rechargez d'abord")
            if etype == "rate_limit_reached_error":
                raise RuntimeError("Compte limité, réduisez la concurrence ou montez de palier")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype or "overloaded", "attente", round(wait, 1), "s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code in (401, 403, 404):
                raise
            if exc.status_code >= 500:
                time.sleep(min(2 ** attempt, 20) + random.random())
            else:
                raise
    raise RuntimeError("Nombre de tentatives épuisé")

print(ask("Expliquez les limites d'usage des nouvelles tentatives"))

Si un en-tête Retry-After est présent, attendez en priorité selon sa valeur, puis ajoutez une gigue aléatoire pour éviter que plusieurs instances ne réessaient simultanément et ne créent une seconde congestion. Plafonnez le nombre de tentatives et déclenchez une alerte en cas d'échec final.

8. Que préparer avant de contacter le support

  1. L'heure de l'incident, avec fuseau et année, à la seconde près.
  2. L'identifiant de requête, le champ id de la réponse et le champ usage.
  3. Le nom du modèle, l'URL de base, le site (chinois ou international) et l'usage du streaming.
  4. Le code HTTP, error.type et le message d'erreur complet.
  5. La version du SDK et du client, la configuration des tentatives, le passage éventuel par un proxy ou une passerelle.
  6. Une requête minimale reproductible, une simple commande curl suffit.
  7. La facture ou l'historique d'usage, pour vérifier une éventuelle double facturation.
  8. Les journaux anonymisés, sans clé, données utilisateur ni prompt sensible.

Reproduisez d'abord le problème en direct avec curl, puis transmettez séparément les résultats du direct et de la passerelle : cela raccourcit nettement le diagnostic.

Questions fréquentes

Une nouvelle tentative après un 429 est-elle facturée deux fois ?

Une requête rejetée par un 429 n'est généralement pas facturée ; une nouvelle tentative réussie l'est comme une requête normale. Le vrai risque est que les tentatives automatiques du SDK transforment une requête métier en plusieurs requêtes, faisant monter à la fois le volume et le coût.

Un modèle qui fonctionnait hier renvoie 404 aujourd'hui, pourquoi ?

Consultez d'abord les retraits sur la page officielle des modèles. La série moonshot-v1 a été retirée le 31 août 2026, les séries kimi-k2 et kimi-latest ne sont plus maintenues ; suivez la recommandation de migration vers kimi-k3.

Un 429 indique un solde insuffisant : faut-il quand même réessayer avec backoff ?

Non. exceeded_current_quota_error relève du solde ou du quota du compte ; réessayer ne rétablit rien. Vérifiez le solde, l'état d'impayé et la validité des bons.

Le streaming est déjà activé, pourquoi un timeout persiste-t-il ?

Le streaming réduit l'attente du premier paquet, mais ne garantit pas une connexion permanente. Vérifiez le timeout d'inactivité du proxy, le timeout de lecture, le plafond de sortie et la stabilité du réseau ; l'amont peut aussi rester longtemps sans nouveau token, ce qui déclenche une coupure par un équipement intermédiaire.

Le direct fonctionne mais la passerelle renvoie une erreur : comment identifier le responsable ?

Envoyez la même clé, le même modèle et la même requête en direct puis via la passerelle, et comparez code de statut, error.type, identifiant de requête et durée. Si le direct réussit et la passerelle échoue, examinez en priorité le chemin, l'authentification, les timeouts et la configuration des tentatives de la passerelle.

Pour aller plus loin

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

Articles liés :