Codes d’erreur DeepSeek expliqués : corriger les erreurs 400, 401, 402, 422, 429, 500 et 503

Les codes d’erreur DeepSeek API expliqués dans ce guide concernent surtout les appels à l’API DeepSeek : requête mal formée, clé API invalide, solde insuffisant, paramètres rejetés, limite de débit, erreur serveur ou serveur surchargé.

La règle la plus importante est simple : ne réessayez pas toutes les erreurs de la même façon. Les erreurs 400, 401, 402 et 422 demandent généralement une correction de votre requête, de votre authentification, de votre compte ou de vos paramètres. Les erreurs 429, 500 et 503 peuvent nécessiter une attente, une réduction de la charge ou une stratégie de retry contrôlée. DeepSeek documente officiellement les codes 400, 401, 402, 422, 429, 500 et 503 avec leurs causes principales et les premières corrections recommandées. Le code 422 doit donc être traité comme un cas de premier niveau, même s’il est parfois oublié dans les titres courts.

Documentation vérifiée le 5 juillet 2026.

Tableau rapide : que faire selon le code d’erreur DeepSeek API ?

Code	Signification	Cause probable	Retry automatique ?	Première action à faire
400	Invalid Format	Corps de requête invalide ou format JSON/API incorrect	Non, pas avant correction	Valider le JSON, les en-têtes et le format attendu
401	Authentication Fails	Clé API absente, incorrecte ou mal transmise	Non	Vérifier Authorization: Bearer DEEPSEEK_API_KEY
402	Insufficient Balance	Solde du compte insuffisant	Non	Vérifier le solde et la facturation
422	Invalid Parameters	Paramètres non acceptés ou incohérents	Non, pas avant correction	Lire le message exact et corriger les paramètres
429	Rate Limit Reached	Trop de requêtes ou trop de connexions concurrentes	Oui, avec prudence	Réduire le débit, limiter la concurrence, appliquer un backoff
500	Server Error	Problème côté serveur DeepSeek	Oui, brièvement	Réessayer après une courte attente et surveiller la répétition
503	Server Overloaded	Serveur surchargé par un trafic élevé	Oui, avec backoff	Attendre, réduire la charge et vérifier le statut du service

Avant de corriger : identifiez d’où vient l’erreur

Avant de modifier votre code, isolez le problème. Une erreur DeepSeek peut venir de quatre zones différentes :

1. La requête : JSON invalide, endpoint incorrect, paramètre non supporté, mauvais modèle, mauvais format de messages.
2. L’authentification : clé API absente, mauvaise variable d’environnement, header Authorization incorrect.
3. Le compte : solde insuffisant, facturation non disponible, consommation supérieure au budget prévu.
4. Le service : surcharge, incident, limite de concurrence ou erreur temporaire côté serveur.

Le test le plus fiable consiste à envoyer une requête minimale avec une clé API valide, le bon base_url, un modèle documenté et un corps JSON simple. DeepSeek indique que son API est compatible avec les formats OpenAI et Anthropic, avec https://api.deepseek.com pour le format OpenAI et https://api.deepseek.com/anthropic pour le format Anthropic.

Exemple minimal en curl :

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Bonjour"}
    ],
    "stream": false
  }'

Si cette requête fonctionne, le problème vient probablement d’un paramètre, d’un outil tiers, du streaming, du mode thinking, des tool calls ou d’une logique propre à votre application.

Erreur DeepSeek 400 — Invalid Format

L’erreur 400 Invalid Format signifie que DeepSeek ne peut pas interpréter correctement le corps de la requête. D’après la documentation officielle, la cause est un format de corps de requête invalide ; la correction consiste à modifier le corps de la requête selon les indications du message d’erreur et le format attendu par l’API.

Causes fréquentes

Les causes les plus courantes sont :

• JSON invalide : virgule en trop, guillemet manquant, accolade non fermée.
• Content-Type absent ou incorrect.
• Mauvais endpoint pour le format utilisé.
• Structure messages incorrecte.
• Champ placé au mauvais niveau.
• Paramètre envoyé dans le mauvais format.
• Confusion entre format OpenAI-compatible et format Anthropic-compatible.
• Historique de conversation mal reconstruit avec le mode thinking ou les tool calls.

Vérifications rapides

Commencez par vérifier ces points :

[ ] Le corps envoyé est un JSON valide.
[ ] Le header Content-Type vaut application/json.
[ ] Le header Authorization est présent.
[ ] Le endpoint correspond au format utilisé.
[ ] Le champ model contient un modèle actuellement documenté.
[ ] messages est un tableau correctement structuré.
[ ] Aucun champ non supporté n’est envoyé par votre SDK ou outil tiers.

Cas particulier : reasoning_content, thinking mode et tool calls

Certaines erreurs 400 peuvent apparaître dans des intégrations agentiques, notamment avec le mode thinking et les tool calls. La documentation DeepSeek indique que, lorsqu’un tour en thinking mode effectue des tool calls, le champ reasoning_content doit être repassé à l’API dans les requêtes suivantes.

Dans certaines intégrations, DeepSeek signale explicitement qu’omettre reasoning_content peut provoquer une erreur 400, et recommande d’utiliser le bon fournisseur ou le bon format selon l’outil.

À vérifier si vous utilisez un agent, un proxy ou un outil compatible OpenAI :

• L’outil supprime-t-il reasoning_content entre deux tours ?
• Le provider configuré est-il bien celui recommandé par l’intégration ?
• Le champ tool_choice est-il supporté dans le mode utilisé ?
• Les messages assistant liés aux tool calls ont-ils un contenu non nul si l’intégration l’exige ?

Faut-il retry une erreur 400 ?

Non. Une erreur 400 indique généralement que la requête est invalide. Réessayer la même requête ne fera que répéter l’échec. Corrigez d’abord le format, puis retestez avec une requête minimale.

Erreur DeepSeek 401 — Authentication Fails

L’erreur 401 Authentication Fails indique que l’authentification a échoué, généralement à cause d’une mauvaise clé API. DeepSeek recommande de vérifier la clé API ou d’en créer une si vous n’en avez pas encore.

Dans la référence API, DeepSeek utilise une authentification HTTP Bearer : la clé doit être transmise dans l’en-tête Authorization.

Format attendu

Authorization: Bearer DEEPSEEK_API_KEY

Avec curl :

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Test"}
    ]
  }'

Causes fréquentes

Une erreur 401 peut venir de :

• clé API copiée partiellement ;
• espace ajouté avant ou après la clé ;
• variable d’environnement non chargée ;
• mauvais nom de variable ;
• clé d’un autre service utilisée par erreur ;
• header Authorization absent ;
• oubli du préfixe Bearer ;
• clé exposée puis révoquée ;
• mauvais environnement : local, staging, production, conteneur, CI/CD.

Diagnostic pratique

Dans votre application, n’affichez jamais la clé complète. Vérifiez seulement qu’elle est bien chargée :

import os

api_key = os.getenv("DEEPSEEK_API_KEY")

if not api_key:
    raise RuntimeError("DEEPSEEK_API_KEY est absente")

print("Clé chargée :", api_key[:6] + "..." + api_key[-4:])

Si la clé est absente dans un conteneur ou un pipeline CI/CD, le problème ne vient pas de DeepSeek mais de la configuration de l’environnement.

Faut-il retry une erreur 401 ?

Non. Le retry ne sert à rien tant que l’authentification n’est pas corrigée. Vérifiez la clé, la variable d’environnement, le header et l’environnement d’exécution.

Erreur DeepSeek 402 — Insufficient Balance

L’erreur 402 Insufficient Balance signifie que le compte n’a plus assez de solde pour exécuter la requête. DeepSeek recommande de vérifier le solde du compte et d’ajouter des fonds via la page de recharge.

DeepSeek indique aussi que les frais sont déduits du solde rechargé ou du solde accordé, et que les prix peuvent varier ; il faut donc consulter régulièrement la page officielle des prix pour les informations les plus récentes.

Que vérifier ?

Vérifiez dans cet ordre :

1. Le compte associé à la clé API.
2. Le solde disponible.
3. Les restrictions éventuelles du compte ou de la facturation.
4. Le modèle utilisé et son coût actuel.
5. Les volumes de tokens consommés par votre application.
6. Les tâches automatisées qui peuvent consommer du crédit en arrière-plan.

Comment réduire le risque de 402 en production ?

Une erreur 402 peut interrompre brutalement une fonctionnalité si aucun contrôle n’est prévu. Pour éviter cela :

• surveillez la consommation quotidienne ;
• ajoutez des alertes de solde bas ;
• limitez les appels inutiles ;
• évitez d’envoyer des prompts trop longs sans nécessité ;
• stockez les réponses réutilisables lorsque cela a du sens ;
• prévoyez un message utilisateur clair en cas de solde insuffisant.

Faut-il retry une erreur 402 ?

Non. Tant que le solde n’est pas restauré ou que la facturation n’est pas corrigée, la même requête échouera.

Erreur DeepSeek 422 — Invalid Parameters

L’erreur 422 Invalid Parameters est importante, car elle fait partie des codes officiellement documentés par DeepSeek. Elle signifie que la requête est bien reçue, mais qu’un ou plusieurs paramètres sont invalides. DeepSeek recommande de corriger les paramètres selon les indications du message d’erreur.

Différence entre 400 et 422

La différence pratique est la suivante :

• 400 Invalid Format : le format global de la requête est invalide ou impossible à lire correctement.
• 422 Invalid Parameters : la requête est lisible, mais certains paramètres sont absents, incohérents, non supportés ou mal configurés.

Par exemple, un JSON cassé mène plutôt à une erreur 400. Un paramètre reconnu mais incompatible avec le modèle, le mode ou le format utilisé peut mener à une erreur 422.

Causes fréquentes

Une erreur 422 peut être causée par :

• modèle non supporté ou obsolète ;
• valeur de paramètre hors plage ;
• paramètre incompatible avec le mode utilisé ;
• mauvais type de données : chaîne au lieu de nombre, objet au lieu de tableau ;
• configuration incorrecte du JSON output ;
• mauvais format de messages ;
• paramètre transmis automatiquement par un SDK ou un proxy.

Exemple : JSON Output mal configuré

Pour le JSON Output, DeepSeek indique qu’il faut définir response_format sur {"type": "json_object"}, inclure le mot “json” dans le prompt système ou utilisateur, fournir un exemple du format attendu et régler max_tokens raisonnablement pour éviter une sortie tronquée.

Si vous activez le JSON mode sans demander clairement du JSON dans le prompt, ou si vous tronquez la sortie avec un max_tokens trop faible, vous pouvez obtenir des comportements inattendus ou des erreurs liées aux paramètres.

Faut-il retry une erreur 422 ?

Non, pas sans correction. Lisez le message exact retourné par l’API, identifiez le paramètre concerné, puis testez une requête plus simple.

Erreur DeepSeek 429 — Rate Limit Reached

L’erreur 429 Rate Limit Reached signifie que vous envoyez les requêtes trop rapidement. DeepSeek recommande de rythmer les requêtes raisonnablement et mentionne, si nécessaire, le recours temporaire à d’autres fournisseurs d’API LLM.

Il faut aussi distinguer le débit simple du nombre de connexions simultanées. Dans sa page Rate Limit & Isolation, DeepSeek documente des limites de concurrence par compte et indique qu’une requête compte comme une connexion concurrente depuis son envoi jusqu’à la fin de la réponse. Ces limites sont calculées au niveau du compte, quel que soit l’API key utilisée. Si la limite de concurrence est dépassée, l’API renvoie HTTP 429.

Causes fréquentes

L’erreur 429 peut apparaître si :

• votre application envoie trop de requêtes en parallèle ;
• plusieurs services utilisent le même compte DeepSeek ;
• des workers ou jobs cron se lancent en même temps ;
• le streaming garde des connexions ouvertes plus longtemps ;
• des retries agressifs amplifient la charge ;
• une file d’attente consomme plus vite que l’API ne peut répondre ;
• un même user_id dépasse sa limite si votre compte dispose de quotas augmentés avec isolation par utilisateur.

Que faire immédiatement ?

Commencez par réduire la pression :

[ ] Réduire le nombre de workers.
[ ] Ajouter une file d’attente.
[ ] Limiter la concurrence par compte et par utilisateur.
[ ] Désactiver les retries instantanés.
[ ] Ajouter du jitter pour éviter les vagues de requêtes simultanées.
[ ] Respecter Retry-After si l’en-tête est présent.
[ ] Mesurer le nombre de connexions ouvertes, pas seulement le nombre de requêtes par minute.

MDN rappelle que le statut HTTP 429 indique qu’un client a envoyé trop de requêtes dans un laps de temps donné et qu’un en-tête Retry-After peut préciser combien de temps attendre avant de réessayer.

Exemple de stratégie de retry avec backoff

L’objectif n’est pas de réessayer plus vite, mais de réessayer plus intelligemment :

import random
import time

def wait_before_retry(attempt: int, retry_after: float | None = None) -> None:
    if retry_after is not None:
        time.sleep(retry_after)
        return

    base = min(2 ** attempt, 30)
    jitter = random.uniform(0, 1)
    time.sleep(base + jitter)

Utilisez cette logique seulement pour les erreurs temporaires comme 429, 500 et 503. Ne l’appliquez pas aveuglément aux erreurs 400, 401, 402 ou 422.

Faut-il changer de modèle ?

Changer de modèle peut aider seulement si votre problème est lié à la charge, au temps de réponse, au coût ou à la concurrence disponible. Mais ne choisissez pas un modèle au hasard. Vérifiez d’abord les modèles actuellement disponibles, leurs limites de concurrence et les paramètres supportés dans la documentation officielle. À la date de vérification de ce guide, DeepSeek liste notamment deepseek-v4-flash et deepseek-v4-pro, avec des limites de concurrence et des informations tarifaires susceptibles d’évoluer.

Erreur DeepSeek 500 — Server Error

L’erreur 500 Server Error signifie que le serveur DeepSeek rencontre un problème. DeepSeek recommande de réessayer après une courte attente et de contacter le support si le problème persiste.

Comment réagir ?

Pour une erreur 500 isolée :

1. Attendez brièvement.
2. Réessayez avec backoff.
3. Vérifiez si l’erreur touche toutes les requêtes ou seulement un payload.
4. Testez une requête minimale.
5. Consultez la page de statut si l’erreur persiste.
6. Contactez le support avec les détails utiles si le problème continue.

Informations utiles à collecter

Avant de contacter le support, conservez :

• timestamp UTC ;
• endpoint appelé ;
• code HTTP ;
• message d’erreur exact ;
• modèle utilisé ;
• type de requête : streaming ou non-streaming ;
• identifiant de requête si disponible ;
• région ou environnement ;
• extrait minimal du payload sans secret ni données sensibles.

Ne transmettez jamais votre clé API dans un ticket, un log ou une capture d’écran.

Faut-il retry une erreur 500 ?

Oui, mais avec retenue. Une erreur 500 peut être temporaire, mais des retries trop rapides peuvent aggraver le problème. Utilisez un backoff exponentiel, limitez le nombre de tentatives, puis basculez vers une dégradation fonctionnelle si le service ne répond pas.

Erreur DeepSeek 503 — Server Overloaded

L’erreur 503 Server Overloaded signifie que le serveur est surchargé à cause d’un trafic élevé. DeepSeek recommande de réessayer après une courte attente.

En HTTP, le statut 503 signifie généralement que le serveur n’est pas prêt à traiter la requête. MDN indique aussi que Retry-After peut être utilisé avec 503 pour indiquer combien de temps le service devrait rester indisponible.

Différence entre 429 et 503

Code	Problème principal	Ce que cela implique
429	Votre rythme ou votre concurrence est trop élevé	Réduisez vos appels, mettez en file d’attente, contrôlez les retries
503	Le service est surchargé ou temporairement indisponible	Attendez, appliquez un backoff, vérifiez le statut, prévoyez un fallback

Dans les deux cas, il ne faut pas lancer des retries immédiats en boucle.

Que faire en production ?

Pour une application en production :

• appliquez un backoff exponentiel avec jitter ;
• imposez une limite stricte de retries ;
• utilisez une file d’attente ;
• affichez un message clair à l’utilisateur ;
• évitez de bloquer toute l’application si seule une fonction IA échoue ;
• surveillez le taux de 503 ;
• consultez la page de statut DeepSeek en cas de hausse soudaine des erreurs.

La page officielle de statut DeepSeek affiche l’état des services et l’historique de disponibilité, notamment pour l’API et le web chat. Elle doit être consultée en cas d’incident, mais elle ne remplace pas vos propres logs, traces, métriques de latence et taux d’erreur.

Cas des requêtes longues, du streaming et du keep-alive

Certaines requêtes DeepSeek peuvent rester connectées pendant un moment avant de recevoir une réponse. La documentation Rate Limit & Isolation indique que, pendant cette attente, les requêtes non-streaming peuvent recevoir des lignes vides et les requêtes streaming des commentaires SSE : keep-alive. Ces contenus ne doivent pas casser votre parsing.

Cela peut être confondu avec un blocage, une erreur serveur ou une mauvaise réponse. Si vous parsez vous-même la réponse HTTP :

• ignorez correctement les lignes vides ;
• gérez les commentaires SSE ;
• distinguez timeout client, keep-alive et vraie erreur HTTP ;
• évitez de couper trop tôt les requêtes longues ;
• mesurez la durée totale jusqu’à la fin de la réponse.

DeepSeek indique aussi que si une requête n’a pas commencé l’inférence après 10 minutes, le serveur ferme la connexion.

Checklist de diagnostic rapide

Utilisez cette checklist avant de conclure que DeepSeek est “down” :

[ ] Le code HTTP exact est connu : 400, 401, 402, 422, 429, 500 ou 503.
[ ] Le message d’erreur complet a été lu.
[ ] Une requête minimale a été testée.
[ ] Le endpoint correspond au format OpenAI ou Anthropic utilisé.
[ ] Le header Authorization contient bien Bearer + la clé API.
[ ] La clé API est chargée dans le bon environnement.
[ ] Le solde du compte est suffisant.
[ ] Le modèle utilisé est encore documenté.
[ ] Les paramètres envoyés sont supportés.
[ ] Les retries ne s’appliquent pas aux erreurs non temporaires.
[ ] La concurrence est limitée côté application.
[ ] Les réponses streaming ou keep-alive sont correctement parsées.
[ ] La page de statut DeepSeek a été consultée en cas de 500/503 répétés.

Quelles erreurs ne faut-il pas retry ?

Ne réessayez pas automatiquement :

• 400, tant que le format de la requête n’est pas corrigé ;
• 401, tant que l’authentification n’est pas corrigée ;
• 402, tant que le solde ou la facturation n’est pas corrigé ;
• 422, tant que les paramètres ne sont pas corrigés.

Vous pouvez réessayer avec prudence :

• 429, après réduction du débit ou de la concurrence ;
• 500, après une courte attente ;
• 503, après une courte attente, idéalement avec backoff et jitter.

Exemple de logique de traitement des erreurs

def should_retry(status_code: int) -> bool:
    return status_code in {429, 500, 503}


def error_action(status_code: int) -> str:
    actions = {
        400: "Corriger le format de la requête avant de réessayer.",
        401: "Vérifier la clé API et le header Authorization.",
        402: "Vérifier le solde et la facturation du compte.",
        422: "Corriger les paramètres selon le message d’erreur.",
        429: "Réduire le débit/concurrence et réessayer avec backoff.",
        500: "Réessayer brièvement, puis contacter le support si persistant.",
        503: "Attendre, réduire la charge et vérifier la page de statut."
    }
    return actions.get(status_code, "Lire le message d’erreur et consulter la documentation.")

Cette logique ne remplace pas les messages détaillés de l’API. Elle sert seulement de garde-fou pour éviter les retries dangereux ou inutiles.

Bonnes pratiques pour éviter les erreurs DeepSeek en production

Une intégration robuste ne se contente pas de gérer les erreurs après coup. Elle les anticipe.

1. Validez les requêtes avant l’envoi

Avant d’appeler l’API, validez :

• la présence du modèle ;
• la structure des messages ;
• les types des paramètres ;
• la taille approximative du prompt ;
• la compatibilité entre mode thinking, JSON output, tool calls et streaming.

2. Centralisez la gestion des erreurs

Ne laissez pas chaque partie de votre application gérer les erreurs DeepSeek différemment. Créez une couche unique qui :

• lit le code HTTP ;
• extrait le message d’erreur ;
• masque les secrets ;
• décide si un retry est autorisé ;
• journalise les informations utiles ;
• retourne un message clair à l’utilisateur.

3. Contrôlez la concurrence

L’erreur 429 peut être liée à la concurrence, pas seulement au nombre de requêtes par minute. DeepSeek précise que les limites de concurrence sont calculées au niveau du compte, quel que soit l’API key utilisée.

Cela signifie que plusieurs services partageant le même compte peuvent se bloquer mutuellement. Utilisez une file d’attente, un pool de workers limité et une supervision par compte.

4. Prévoyez une dégradation fonctionnelle

Si DeepSeek renvoie trop de 500 ou 503 :

• affichez une réponse temporaire ;
• placez la tâche en file d’attente ;
• proposez de réessayer plus tard ;
• désactivez temporairement les tâches non essentielles ;
• utilisez un fallback si votre produit l’exige.

Le fallback doit être une décision produit et technique, pas une réaction improvisée.

5. Surveillez les tendances, pas seulement les erreurs isolées

Une erreur unique n’a pas la même signification qu’une hausse soudaine de 429, 500 ou 503. Surveillez :

• le taux d’erreur par code ;
• la latence ;
• le nombre de connexions concurrentes ;
• le coût par fonctionnalité ;
• la consommation de tokens ;
• les retries par minute ;
• les erreurs par modèle et par environnement.

FAQ

Que signifie un code d’erreur DeepSeek ?

Un code d’erreur DeepSeek indique pourquoi une requête API a échoué : format invalide, authentification incorrecte, solde insuffisant, paramètres invalides, limite atteinte ou problème serveur. Le code HTTP vous aide à savoir si vous devez corriger votre requête, votre compte ou attendre avant de réessayer.

Comment corriger l’erreur DeepSeek 400 ?

Validez le JSON, vérifiez Content-Type: application/json, confirmez le bon endpoint, simplifiez le payload et comparez votre structure avec l’exemple officiel. Si vous utilisez thinking mode ou tool calls, vérifiez aussi la gestion de reasoning_content.

Pourquoi ai-je une erreur 401 avec DeepSeek ?

Une erreur 401 signifie généralement que la clé API est absente, incorrecte ou mal envoyée. Vérifiez la variable DEEPSEEK_API_KEY, le header Authorization: Bearer ..., l’environnement d’exécution et le compte associé à la clé.

Que faire en cas d’erreur 402 Insufficient Balance ?

Vérifiez le solde du compte, la page de facturation, le modèle utilisé et votre consommation. Ne relancez pas la requête tant que le solde ou la configuration de paiement n’est pas corrigé.

Quelle est la différence entre 400 et 422 ?

L’erreur 400 concerne plutôt un format de requête invalide. L’erreur 422 concerne plutôt des paramètres invalides dans une requête que l’API peut lire. Dans les deux cas, il faut corriger le payload avant de réessayer.

Comment corriger une erreur 429 DeepSeek ?

Réduisez le débit, limitez le nombre de requêtes concurrentes, ajoutez une file d’attente et appliquez un backoff exponentiel avec jitter. Si un en-tête Retry-After est présent, respectez-le.

Quelle différence entre 500 et 503 ?

L’erreur 500 indique un problème serveur général. L’erreur 503 indique plutôt que le serveur est indisponible ou surchargé. Dans les deux cas, réessayez avec prudence, mais consultez la page de statut si l’erreur persiste.

Quand faut-il contacter le support DeepSeek ?

Contactez le support si une erreur 500 persiste, si une erreur 503 dure anormalement, si une erreur 401 survient malgré une clé valide, ou si le comportement ne correspond pas à la documentation. Fournissez les détails techniques utiles, mais jamais votre clé API.