Table des erreurs : Claude Code et Codex sur une API tierce

Comment utiliser cette table

Ne cherchez pas immédiatement la réponse dans le texte de l'erreur : déterminez d'abord quelle couche a échoué. Presque toutes les erreurs d'un client IA proviennent de ces cinq couches :

1. Couche réseau : la requête n'a jamais atteint le serveur
2. Couche authentification : elle est arrivée, mais la clé n'est pas reconnue
3. Couche protocole : la clé est reconnue, mais le chemin ou le format ne va pas
4. Couche modèle : le protocole passe, mais le modèle n'existe pas
5. Couche contexte : le modèle tourne, mais l'entrée est trop longue

L'intérêt du découpage : la correction est totalement différente d'une couche à l'autre, et le texte de l'erreur ne dit presque jamais dans laquelle vous vous trouvez.

Diagnostic par statut HTTP

Ces commandes vérifient la liste des modèles et trois protocoles, avec le statut HTTP de chaque requête :

Définissez votre clé API KimiSeek dans le terminal où vous exécuterez curl, en remplaçant la valeur d’exemple. Une clé enregistrée dans votre client ne remplit pas automatiquement cette variable du shell :

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

Lisez le statut HTTP affiché après chaque réponse ainsi que error.code, error.type et message dans le corps. L’étape qui échoue ne suffit pas à déterminer la prise en charge du protocole. Une liste de modèles en 200 valide la clé, pas le solde : un compte sans solde peut obtenir 200 à l’étape 1 et 402 à l’étape 2.

Côté Claude Code

Aucun identifiant

Invalid API key · Please run /login

Ce message indique que Claude Code n'a récupéré aucun identifiant. Vérifiez que ANTHROPIC_AUTH_TOKEN est bien actif dans le shell qui a lancé Claude Code — l'erreur classique étant d'exporter dans un terminal et de démarrer le client dans un autre.

401, échec d'authentification

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

Causes par ordre de probabilité :

1. un espace ou un saut de ligne a été copié avec la clé
2. la clé a été révoquée ou son quota est épuisé
3. ANTHROPIC_API_KEY est défini mais vide, et le client retombe sur un état connecté

403 forbidden

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

En direct, ce message signifie généralement que la clé est invalide ; via une passerelle, la cause la plus fréquente est une écriture incorrecte de l'en-tête : certaines passerelles n'acceptent que Authorization: Bearer, d'autres seulement x-api-key. KimiSeek accepte les deux, mais si vous avez en plus un proxy au milieu, l'en-tête peut être réécrit.

model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

Deux possibilités : un nom de modèle mal orthographié, ou un modèle retiré du catalogue. Un id retiré continue de renvoyer not found au lieu d'indiquer qu'il est retiré, et c'est le piège qui fait perdre le plus de temps — vous passez un long moment à auditer la configuration alors que la vraie réponse est que le modèle a changé de génération.

Remplacez-le par un id réel depuis la page des modèles.

Le flux se coupe en cours de route

API Error: stream disconnected before completion: stream closed before completion

La connexion en flux a été interrompue en cours de route. Vérifiez dans cet ordre :

1. si un proxy HTTP local (HTTPS_PROXY) intercepte la requête
2. si le réseau d'entreprise applique un timeout sur les réponses longues
3. si une limite de durée par requête a été déclenchée côté serveur

Le délai d’expiration des requêtes vers le fournisseur est de 600 secondes pour /v1/messages (Claude Code) et de 175 secondes pour /v1/responses (Codex). Le client ou un proxy intermédiaire peut couper la connexion plus tôt ; vérifiez l’endpoint utilisé et le détail de l’erreur.

Dépassement de contexte

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

Notez que le 200000 affiché ici est la limite du client ou du modèle, et pas nécessairement le chiffre que vous attendiez. Sur DeepSeek V4 Pro, la limite réelle est de 1M : si vous voyez 200000, c'est que la requête n'a pas atteint le modèle visé, ou que le client a tronqué selon les spécifications de Claude.

Côté Codex

401 Missing bearer

■ unexpected status 401 Unauthorized: Missing bearer

env_key dans config.toml n'est qu'un nom de variable : la valeur réelle doit être présente dans l'environnement. Ce message dit exactement « le nom de variable est écrit, mais la variable d'environnement est vide ».

404 Not Found

■ unexpected status 404 Not Found

Huit fois sur dix, il manque /v1 dans base_url. Codex assemble base_url + "/responses" : sans le /v1, la requête tombe sur un chemin du site.

Après avoir vérifié base_url, examinez aussi si le corps signale un modèle introuvable. Si /v1/responses est réellement absent, utilisez une passerelle ou une couche de conversion compatible ; Codex actuel refuse wire_api = "chat". Voir le guide Codex.

Interruption de flux

■ stream disconnected before completion

Même problème de flux que côté Claude Code, mais Codex y est plus sensible — sa boucle d'exécution dépend d'un flux d'événements complet. Sur un réseau instable, changez de réseau plutôt que de compter sur des tentatives répétées.

Deux pannes réseau typiques

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed est l'erreur réseau générique de Node : prise littéralement, elle n'apporte aucune information. Pour connaître la cause réelle, il faut regarder la ligne ECONNREFUSED — si elle pointe vers un port local du type 127.0.0.1:7890, c'est qu'un proxy local a pris la requête en charge, et que ce proxy ne tourne pas ou que ses règles sont fausses.

C'est la panne la plus souvent prise à tort pour « la passerelle est tombée ». La méthode de diagnostic : si curl passe mais pas le client, c'est presque toujours que les variables d'environnement du shell du client diffèrent de celles du shell où tourne curl.

Un même message, des causes différentes en direct et via une passerelle

C'est le modèle mental le plus utile à se construire quand on passe par une passerelle :

Ce qu'il faut joindre quand vous demandez de l'aide

Si vous interrogez quelqu'un (ou ouvrez un ticket), ces quatre éléments sont indispensables, sinon personne ne pourra localiser le problème :

1. le texte complet de l'erreur (une ligne entière, pas une capture d'écran tronquée)
2. le résultat de la sonde curl par couches — laquelle des quatre étapes a échoué
3. la version du client (claude --version / codex --version)
4. l'id du modèle et la Base URL utilisés (clé masquée)

Date de vérification

• Date de vérification : 2026-10-26
• Les exemples servent à localiser la panne ; les messages peuvent varier selon la version du client. Indiquez votre version installée lors du signalement. La configuration Codex a été vérifiée avec 0.154.0.