Les développeurs qui cherchent « erreurs API Midjourney » ne trouvent généralement pas de table officielle des codes. Midjourney n'a pas d'API publique universelle : vous appelez le plus souvent une encapsulation tierce ou une passerelle relais, dont les codes, champs d'erreur et règles de tentative sont définis par le fournisseur. Un même 401 peut avoir des causes différentes chez deux plateformes.

Cet article classe les pannes courantes selon la sémantique HTTP et le cycle de vie des tâches, propose un ordre de diagnostic, des patterns de retry et d'idempotence, ainsi qu'une liste pour les tickets. Les interfaces, codes et tarifs font foi dans la documentation du fournisseur.

Remarque : Midjourney est une marque de Midjourney, Inc. ; Discord est une marque de Discord Inc. Les encapsulations et relais tiers discutés ici n'ont aucune affiliation avec ces sociétés ; interfaces, codes d'erreur et facturation dépendent de leur documentation.

1. Localiser d'abord la couche où survient l'erreur

Un appel traverse cinq couches : client et réseau, authentification de la passerelle, pool de comptes amont, tâche de génération, stockage des résultats et CDN. Les symptômes diffèrent selon la couche :

Symptôme Couche probable Première action
Toutes les interfaces échouent Client, réseau, DNS, proxy Changer de réseau ou reproduire avec une requête minimale
Seul Midjourney échoue Canal ou pool de comptes amont Consulter la page d'état du fournisseur et les autres modèles
4xx à la soumission Authentification, paramètres, limitation Vérifier la requête selon le code d'erreur
Soumission réussie mais tâche échouée Génération, modération, compte amont Lire le champ d'erreur de la tâche
Tâche réussie mais image inaccessible Lien de résultat, CDN, téléchargement Vérifier la validité du lien et retenter le téléchargement

Posez d'abord trois questions : tout échoue-t-il ou seulement certains cas ? La soumission échoue-t-elle ou la tâche ? Est-ce reproductible à l'identique ou seulement aux heures de pointe ? Ces réponses réduisent déjà de moitié le périmètre.

2. 401 et 403 : authentification, permissions et état du compte

Le 401 signifie que l'identité n'est pas reconnue. Causes fréquentes : en-tête absent ou mal orthographié, clé avec espace superflu ou déjà renouvelée, cookie web ou token temporaire utilisé comme clé API, URL de base erronée, ou dérive d'horloge système invalident une signature.

Le 403 signifie que l'identité est reconnue mais n'a pas accès. Causes fréquentes : clé non ouverte au modèle, IP hors liste blanche, restriction géographique, offre expirée, compte sous contrôle de risque, permissions d'espace de travail insuffisantes.

Ordre de traitement :

  1. Reproduire avec une requête minimale, en ne gardant que l'en-tête d'authentification et les paramètres obligatoires.
  2. Vérifier le nom et le préfixe de l'en-tête dans la documentation, notamment l'espace après Bearer.
  3. Confirmer dans la console l'état de la clé, les droits sur le modèle, le solde et la date d'expiration.
  4. Essayer une clé de test nouvellement créée ; si le 403 persiste, demander au fournisseur l'état de l'IP, de la région et du pool de comptes.

N'écrivez pas la clé dans un front-end ou un dépôt public. En cas de 401, suspectez d'abord la configuration et n'enchaînez pas les tentatives : réessayer ne rendra pas une mauvaise clé correcte.

3. 429 : limitation, concurrence et quota

La signification du 429 est plus large qu'on ne le pense. Il peut indiquer un dépassement du nombre de requêtes par minute, du nombre de tâches simultanées, du quota quotidien, l'absence temporaire de compte disponible dans le pool, ou une file amont saturée. Chaque cause appelle un traitement différent.

Examinez les en-têtes et le corps : si Retry-After est présent, attendez la durée indiquée ; une mention quota ou balance suggère un problème de solde ; une mention concurrency ou queue suggère la concurrence ; si toutes les clés reçoivent 429 en même temps, le pool du fournisseur est probablement saturé.

Réponses possibles :

  • Ajouter une file côté client, limiter la concurrence, éviter les pics instantanés.
  • Appliquer un backoff exponentiel avec jitter pour éviter des tentatives simultanées.
  • Distinguer « attendre un peu » de « recharger ou augmenter le quota ».
  • Enregistrer modèle, plage horaire et volume des 429 pour savoir s'il s'agit de votre trafic ou de la capacité amont.

Un 429 ne se règle pas en réessayant plusieurs fois : les tentatives aveugles allongent la file et peuvent prolonger un blocage.

4. Prompt refusé : modération et erreurs de paramètres

Un « prompt refusé » a deux origines. La modération de contenu : violence, contenu sexuel, mineurs, célébrités réelles, personnages protégés, marques, personnalités politiques, etc. Les erreurs de paramètres : format non pris en charge, version de modèle inexistante, prompt trop long, URL d'image de référence inaccessible ou format non supporté.

Dans les deux cas, ne réessayez pas à l'identique. Pour un refus de modération, ajustez le matériau et la formulation, sans contourner par des synonymes, des caractères découpés ou des descriptions obscures. Pour une erreur de paramètre, corrigez les champs selon la documentation. Consignez les prompts refusés, la version du modèle et le corps de réponse pour constituer une liste noire et des règles de contrôle d'équipe.

Distinguez aussi « refusé » et « échoué » : le premier intervient généralement avant la génération, le second peut avoir déjà généré un coût, selon les règles du fournisseur.

5. Tâche échouée, timeout et résultat expiré

Les causes d'échec incluent une erreur interne amont, un compte anormal, des paramètres invalides, l'échec de téléchargement d'une image de référence, une interruption de modération et un timeout de file. Lisez le champ d'erreur, pas seulement « failed ».

Il existe trois timeouts : le timeout de lecture côté client, où la requête a peut-être atteint le serveur ; le timeout de soumission, où la tâche a peut-être été créée sans que la réponse revienne ; le timeout de polling, où la tâche tourne encore mais la fenêtre d'attente est terminée.

Le plus dangereux est de resoumettre immédiatement après un timeout de soumission : la tâche d'origine peut exister, ce qui entraîne un double débit. La bonne pratique : joindre une clé d'idempotence ou un numéro de requête métier à la soumission ; après un timeout, rechercher d'abord les tâches récentes par numéro de requête ; ne réessayer qu'après confirmation d'absence. Si le fournisseur ne gère pas l'idempotence, utilisez une fenêtre de déduplication dans la table des tâches.

L'expiration du résultat est un autre problème. Le succès renvoie souvent une URL temporaire, valable de quelques minutes à quelques jours ; ne la stockez pas comme adresse de l'œuvre. Transférez immédiatement vers votre stockage objet et ne conservez en base que votre chemin et l'ID de tâche.

6. Échec de téléchargement : 403, 404 et fichier tronqué

Un échec de téléchargement ne signifie pas que la génération a échoué. Cas fréquents : URL signée expirée renvoyant 403 ; résultat nettoyé renvoyant 404 ; proxy ou réseau interrompu provoquant une réinitialisation de connexion ; page d'erreur HTML enregistrée comme image ; fichier téléchargé à moitié.

Le téléchargement doit être conçu séparément : vérifier Content-Type et la taille du fichier ; écrire dans un fichier temporaire puis renommer atomiquement en cas de succès ; réessayer sur 5xx et erreurs réseau ; sur 403/404, ne pas relancer la génération mais consulter l'état de la tâche pour savoir si le résultat existe encore. Quand le fournisseur propose plusieurs adresses de résultat, prévoyez un domaine de secours ou un canal de transfert alternatif.

7. Retry et idempotence : éviter que l'échec devienne double facturation

Le principe du retry est de classer, non de boucler uniformément. 401, 403, 400, 422 et refus de modération ne doivent pas être réessayés avant correction de la configuration ou du prompt ; 429 attend selon Retry-After ; 5xx, réinitialisation de connexion et timeout de lecture peuvent être réessayés avec backoff ; un timeout de soumission exige d'abord une vérification de la tâche.

import random
import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def post_with_retry(url, headers, payload, request_id, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(
                url,
                headers={**headers, "Idempotency-Key": request_id},
                json=payload,
                timeout=(10, 60),
            )
        except (requests.Timeout, requests.ConnectionError):
            if attempt == max_attempts:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))
            continue

        if resp.status_code in RETRYABLE:
            retry_after = resp.headers.get("Retry-After", "")
            wait = int(retry_after) if retry_after.isdigit() else 2 ** attempt
            time.sleep(min(wait + random.random(), 60))
            continue

        if resp.status_code >= 400:
            raise RuntimeError(f"{resp.status_code}: {resp.text[:200]}")
        return resp.json()

    raise RuntimeError("budget de tentatives epuise")

Le champ Idempotency-Key n'est qu'une convention courante : son support et son nom exact dépendent de la documentation du fournisseur. Sans clé d'idempotence, un numéro de requête métier avec déduplication dans la table des tâches produit le même effet.

8. Liste de vérification avant d'ouvrir un ticket

  1. Noter l'heure, le fuseau horaire et la durée de l'incident.
  2. Joindre l'ID de requête, l'ID de tâche et le numéro métier.
  3. Préciser l'adresse de l'interface, le nom du modèle et la version de l'API.
  4. Joindre le code HTTP complet et le corps de réponse, en masquant clé et données personnelles.
  5. Décrire les paramètres, le nombre d'images de référence et le format, pas seulement « la génération échoue ».
  6. Indiquer le nombre de tentatives, leur intervalle, l'environnement réseau et la région de sortie.
  7. Fournir une reproduction minimale et le résultat avec un autre modèle et les mêmes paramètres.
  8. Préciser l'impact : combien de tâches échouées, si la livraison en production est affectée.

L'information la plus utile dans un ticket est le modèle précis, la région, la plage horaire, les paramètres et les ID de trois requêtes, pas « l'interface ne marche pas ».

9. Surveillance et prévention

Transformez les erreurs en indicateurs : par modèle, suivez la proportion de 401, 403, 429, 5xx, tâches échouées, timeouts et échecs de téléchargement ; enregistrez la durée P95 ; vérifiez chaque jour si les tâches échouées sont facturées. Définissez des alertes sur le taux de 429, d'échec de tâche et d'échec de téléchargement, plutôt que d'attendre les plaintes.

Prévention quotidienne : séparer les clés par environnement et projet, plafonner les clés de test, limiter la concurrence, fixer un nombre maximal de tentatives et une file de messages morts par type de tâche. Avec une encapsulation tierce, vérifiez la page d'état, le délai de réponse et le plan d'arrêt ; ne concentrez pas tout le trafic sur un canal sans SLA.

Questions fréquentes

Que faire si un 401 persiste après changement de clé ?

Vérifiez d'abord que la nouvelle clé est active et dispose des droits sur le modèle, puis le préfixe d'en-tête, l'URL de base et l'horloge système. Si les autres modèles fonctionnent, le problème vient peut-être du pool de comptes amont.

Un 429 signifie-t-il un solde insuffisant ?

Pas nécessairement. Le 429 peut relever de la fréquence, de la concurrence, du quota ou de la capacité du pool. Lisez les en-têtes et le corps ; une mention quota ou balance rend le problème de solde plus probable.

Peut-on resoumettre directement après un timeout de tâche ?

Ce n'est pas conseillé. Un timeout de soumission ne signifie pas que la tâche n'a pas été créée ; resoumettre peut entraîner un double débit. Recherchez d'abord par numéro de requête ou ID de tâche, puis réessayez après confirmation d'absence ; joignez si possible une clé d'idempotence.

Peut-on récupérer un résultat dont le lien a expiré ?

Cela dépend de la conservation côté fournisseur. Consultez l'état de la tâche ; si le résultat a été nettoyé, il faut généralement régénérer. En production, transférez dès le succès pour ne pas dépendre d'un lien temporaire.

Midjourney traite-t-il les erreurs des interfaces tierces ?

Non. Une encapsulation tierce n'a aucune affiliation avec Midjourney ; c'est au fournisseur de diagnostiquer. Midjourney ne dispose pas non plus d'un canal de support pour une API publique.

Étape suivante

Classez d'abord les erreurs en cinq catégories — authentification, limitation, contenu, tâche, téléchargement — puis décidez ce qui doit être réessayé et ce qui doit alerter. Pour un point d'entrée unifié, créez une clé sur ZSQH AI Gateway et vérifiez les modèles et la facturation sur la page Tarifs des modèles.

À lire aussi :