Les erreurs de l'API DeepSeek se répartissent en quatre grandes familles : authentification, chemin et nom de modèle, limitation de débit, timeout. Le bon ordre de diagnostic est le suivant : lire d'abord le code HTTP et le type d'erreur, puis l'identifiant de requête et une reproduction minimale, et seulement ensuite modifier le prompt ou changer de modèle. Inverser cet ordre conduit facilement à prendre un problème de configuration pour une limite du modèle.

Cet article détaille les quatre familles 401, 404, 429 et timeout, avec les causes, les étapes de vérification et un code de backoff réutilisable. Les modèles et les tarifs font foi sur la page Tarifs des modèles.

Remarque : DeepSeek est une marque de son détenteur. Les types d'erreur, les règles de limitation et le comportement de l'interface peuvent changer selon les versions. Cet article décrit les situations courantes d'octobre 2026 ; la documentation du fournisseur fait foi.

1. Distinguer d'abord les quatre familles

Statut ou symptôme Signification courante Cause typique Ordre de traitement
401 Échec d'authentification Clé erronée, Bearer absent, clé expirée Corriger d'abord les identifiants
404 Chemin ou modèle inexistant URL de base erronée, nom de modèle obsolète, chemin dupliqué Vérifier l'adresse et le nom du modèle
429 Limitation ou quota atteint Pic de concurrence, clé partagée, tempête de tentatives Backoff, réduire la concurrence
Timeout Délai de connexion ou de lecture Réseau, sortie longue, modèle de raisonnement, proxy Diagnostiquer par couche
400 Paramètres ou contexte invalides Contexte dépassé, format incorrect Quantifier puis découper
5xx Erreur du service amont Panne ou surcharge du serveur Backoff, changer de canal

Journalisez au minimum l'heure, le code de statut, le type d'erreur, le nom du modèle, la durée et l'identifiant de requête. N'enregistrez jamais la clé complète et n'imprimez pas le texte utilisateur intégral dans les journaux.

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

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. Vérifiez dans cet ordre :

  1. L'en-tête est-il Authorization: Bearer <clé> et non un autre mode d'authentification.
  2. La clé contient-elle des espaces, sauts de ligne ou guillemets superflus ? Une copie depuis une fenêtre de chat en apporte souvent.
  3. La variable d'environnement est-elle réellement chargée ? Affichez seulement son préfixe pour le confirmer.
  4. La clé a-t-elle été supprimée, renouvelée ou désactivée.
  5. L'URL de base et la clé appartiennent-elles à la même plateforme ? Une clé du fournisseur avec l'adresse d'une passerelle renvoie 401.
  6. Le reverse proxy a-t-il écrasé ou supprimé l'en-tête Authorization.
export DEEPSEEK_API_KEY="sk-votre-clé"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Réponds seulement OK"}],
    "max_tokens": 16
  }'

Si cette commande renvoie 200, la clé, l'URL de base et le nom du modèle sont tous corrects. Si le 401 persiste, testez une nouvelle clé sur une requête minimale pour distinguer un problème de clé d'un problème de proxy ou de configuration de passerelle.

3. 404 : l'adresse et le nom du modèle sont les erreurs les plus fréquentes

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

  • L'URL de base pointe vers un autre fournisseur, ou /v1 est en trop ou manquant.
  • Le SDK ajoute automatiquement /chat/completions et le chemin est écrit une seconde fois à la main.
  • Le nom du modèle utilise une ancienne version retirée, ou la casse et le suffixe ne correspondent pas.
  • L'adresse de la passerelle et celle du fournisseur sont mélangées, alors que les règles de chemin diffèrent.
  • Une règle de réécriture du reverse proxy casse le chemin.

Commencez par appeler l'adresse complète avec curl et lisez le message d'erreur du corps de réponse, puis comparez l'URL de base et le nom du modèle avec la page tarifs du site. Ne codez pas plusieurs adresses en dur : configurez-les par environnement pour éviter de propager une adresse de test en production.

4. 429 : une limitation, pas un solde insuffisant

Un 429 indique que la requête dépasse une limite de débit, de concurrence ou de quota. DeepSeek peut limiter ou mettre en file les requêtes aux heures de pointe ; les règles exactes figurent dans la documentation du fournisseur. Scénarios fréquents :

  • Plusieurs services partagent une clé et se disputent le quota.
  • Des tâches par lot démarrent à l'heure pile et créent 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 consomment davantage de ressources et réduisent la marge de concurrence.
Symptôme Cause probable Traitement
429 concentrés aux heures de pointe Charge amont ou pic de trafic File d'attente, envoi lissé, décalage horaire
429 avec une clé partagée entre services Quota partagé Une clé par projet
Aggravation après les tentatives Nouvelles tentatives sans backoff Backoff exponentiel avec gigue
429 d'abord sur les requêtes longues Tokens de sortie élevés Réduire max_tokens ou la concurrence 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-votre-clé",
    base_url="https://api.deepseek.com",
    max_retries=0,  # désactive les tentatives automatiques du SDK pour éviter le cumul
)

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

print(ask("Explique en une phrase ce qu'est une limitation de débit"))

Les nouvelles tentatives ne conviennent 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. Timeouts : distinguer connexion, lecture et streaming

Un timeout ne signifie pas que le service est indisponible. Localisez d'abord le segment bloqué :

Symptôme Cause probable Traitement
Timeout de connexion DNS, sortie réseau, proxy injoignable Vérifier réseau et proxy, changer de liaison
Premier token très lent File amont, prompt trop long Raccourcir l'entrée, décaler, modèle plus léger
Timeout de lecture Sortie trop longue, raisonnement long Augmenter le timeout de lecture, limiter la sortie
Rupture du streaming Gigue réseau, coupure du proxy Reconnexion, conserver le contenu déjà reçu
Timeout général simultané Sortie locale ou panne amont Basculer sur le canal de secours, consulter l'état du service 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-votre-clé",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

Les timeouts de connexion et de lecture doivent être réglés séparément. Une valeur unique très élevée bloque le pool de threads en cas d'incident ; une valeur trop basse tue des tâches longues légitimes. Configurer par type de tâche est plus sûr.

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 un 401, vérifiez la clé, l'en-tête, la variable d'environnement et la cohérence de plateforme.
  3. Pour un 404, vérifiez l'URL de base, la concaténation du chemin et le nom du modèle.
  4. Pour un 400, vérifiez les paramètres, la longueur du contexte, le format d'image ou de fichier.
  5. Pour un 429, vérifiez la concurrence, le partage de clé, la stratégie de tentatives et les heures de pointe.
  6. Pour un timeout, vérifiez DNS, proxy, longueur de sortie et réglage du timeout de lecture.
  7. Pour un 5xx, appliquez un backoff puis contactez le prestataire avec l'identifiant de requête si le problème persiste.
  8. Après chaque incident, ajoutez supervision et alertes au lieu d'attendre le retour des utilisateurs.

7. Supervision et journaux

Champ Utilité
Heure et projet Localiser les pics et l'étendue de l'impact
Code de statut et type d'erreur Distinguer authentification, limitation et erreur amont
Identifiant de requête Preuve clé pour le diagnostic avec le prestataire
Nom et version du modèle Savoir si l'erreur suit un changement de modèle
Tokens d'entrée et de sortie Analyser les coûts et les requêtes longues
Durée et nombre de tentatives Détecter la queue de latence et les tempêtes de tentatives

Comptez au minimum par heure les 401, 404, 429, timeouts et 5xx. En cas de hausse brutale, vérifiez d'abord si elle se concentre sur un projet, une clé ou un modèle, puis décidez de réduire la concurrence, changer de canal ou revenir à la version précédente.

Questions fréquentes

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 une explication dans le corps de réponse. Vérifiez d'abord la concurrence et le partage de clé, puis le solde du compte.

Quelle est la cause la plus fréquente d'un 404 ?

Une URL de base erronée, un chemin concaténé deux fois et un nom de modèle expiré. Appelez l'adresse complète avec curl, puis comparez le nom du modèle à la page tarifs : la localisation prend souvent quelques minutes.

Faut-il réessayer indéfiniment après un timeout ?

Non. Les tentatives doivent avoir une limite, un backoff et une alerte ; un timeout peut aussi signifier que la requête s'est déjà exécutée en amont. Pour les opérations à effet de bord, vérifiez l'état avant de renvoyer.

Que faire si le streaming s'interrompt ?

Notez le contenu déjà reçu et la position d'interruption, puis déterminez s'il s'agit d'une gigue réseau, d'une coupure du proxy ou d'un timeout amont. Le client doit gérer la reconnexion et la déduplication, sans stocker un contenu partiel comme résultat complet.

Comment distinguer une erreur de passerelle d'une erreur du fournisseur ?

Conservez l'identifiant de requête et le type d'erreur, puis envoyez la même requête à l'entrée du fournisseur et à celle de la passerelle. Vous distinguerez rapidement clé, réseau, configuration de passerelle et service amont.

Pour aller plus loin

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

Articles liés :