Erreurs d'API : causes et solutions
Chaque article commence par la réponse et fournit une commande pour confirmer la cause vous-même. Les messages d'erreur sont laissés en anglais, tels qu'ils apparaissent dans votre terminal.
Unexpected token '<' lors d'un appel à une API compatible OpenAIVotre client a reçu du HTML là où il attendait du JSON. Presque toujours, il manque /v1 à la base URL, ou il y figure deux fois. Comment le confirmer en une commande et comment le corriger.401 invalid API key : quand la clé semble correcte mais échoue quand mêmeUn 401 avec une clé que vous venez de copier se résume généralement à un espace parasite, au mauvais en-tête, ou à une clé limitée à des modèles qu'elle ne peut pas atteindre. Comment savoir lequel vous concerne.404 sur /v1/chat/completions alors que l'endpoint existe bel et bienRecevoir un 404 d'un endpoint que vous savez actif, c'est presque toujours un GET là où l'API attend un POST, ou un chemin décalé d'un segment. Comment les distinguer.Timeout 524 sur les requêtes API longuesUn 524 vient d'un CDN placé devant l'API, pas du modèle. Il se déclenche quand l'origine n'envoie rien pendant trop longtemps, ce qui explique pourquoi les requêtes en streaming survivent et les autres non.Model not found : quand le nom du modèle est presque justeCette erreur signifie presque toujours que le nom du modèle ne correspond pas exactement, ou que votre clé n'a pas accès à ce modèle. Comment lister ce que vous pouvez réellement appeler.Un 429 d'une passerelle d'API peut signifier deux choses différentesUne passerelle renvoie 429 aussi bien quand votre solde est épuisé que quand l'amont est saturé. L'un vaut la peine d'être relancé, l'autre jamais. Comment les distinguer d'après le corps de la réponse.Erreur CORS lors d'un appel à une API IA depuis le navigateurL'erreur CORS est le symptôme. Le vrai problème, c'est qu'une requête depuis le navigateur transmet votre clé d'API à chaque visiteur. Quoi faire à la place, et pourquoi aucun réglage d'en-tête ne le corrige.400 en forçant un appel d'outil sur un modèle de raisonnementRégler tool_choice sur any ou tool est refusé par les modèles qui raisonnent toujours avant de répondre. Quoi envoyer à la place, et les autres paramètres que ces modèles refusent.Les requêtes meurent à exactement 100 secondes derrière CloudflareUne longue génération échoue presque exactement à 100 secondes avec un 524 ou un flux coupé. Ce chiffre est une limite du proxy Cloudflare, pas de votre serveur. Comment le confirmer et les trois façons de le contourner.Le modèle renvoie une chaîne vide, mais vous êtes quand même facturéLa réponse arrive avec HTTP 200, content est une chaîne vide et le journal d'utilisation montre des tokens de sortie facturés. Sur les modèles de raisonnement, c'est presque toujours max_tokens épuisé avant qu'un texte visible ne soit produit.Une réponse en streaming s'arrête au milieu d'une phraseDes tokens arrivent, puis s'arrêtent, et aucune erreur n'est levée. La différence entre un flux terminé et un flux coupé tient en une ligne dans le corps SSE, et la plupart du code client ne la vérifie jamais.Un modèle qui fonctionnait hier échoue désormais pour tout le monde dans le même groupe de clésUn modèle qui fonctionnait se met à renvoyer des erreurs pour toutes les clés d'un groupe, tandis que les autres groupes ne sont pas touchés. C'est du routage, pas le modèle : un seul compte amont défaillant peut faire tomber tout un groupe.La facture est plus élevée que ne le justifie le nombre de tokensVos totaux de tokens paraissent modestes, mais pas le montant. Sur les modèles de la famille Claude, la cause habituelle est le sens du cache : une écriture en cache coûte plus qu'une entrée ordinaire, une lecture en coûte une fraction, et les mêmes tokens peuvent varier d'un facteur douze.Claude Code et Codex ont besoin de base URL différentes sur la même passerelleLa même passerelle, la même clé, deux agents de code, et une base URL qui fonctionne dans l'un échoue dans l'autre. La règle est simple dès que l'on sait quel client ajoute le chemin lui-même.405 Method Not Allowed lors d'un appel à une API IAUn 405 sur un endpoint IA ne signifie presque jamais que la méthode est mauvaise. Il signifie que le POST a atterri à un endroit qui ne sert que des pages, généralement le domaine nu, parce qu'il manque /v1 à la base URL. Comment le confirmer en une commande.404 sur /responses : la Responses API a aussi besoin du préfixe de versionLes clients qui passent de chat/completions à la Responses API perdent souvent le préfixe de version. Le 404 vient de la périphérie du réseau, avant l'exécution de tout code d'API, donc l'appel n'apparaît jamais dans votre journal d'utilisation.context_length_exceeded : ce qui compte vraiment dans la limiteLa limite couvre toute la conversation plus l'espace réservé à la réponse, pas seulement votre dernier message. Pourquoi raccourcir le prompt n'aide souvent pas, et quoi couper à la place.529 overloaded_error de Claude : ce que c'est et que faire529 signifie que l'amont est saturé en ce moment. Ce n'est pas un problème de quota ni quelque chose que votre clé peut corriger. Comment le distinguer d'un 429, et le schéma de relance qui aide vraiment.401 avec une clé qui est forcément correcte : vérifiez le format de l'en-têteUne clé peut être parfaitement valide et produire quand même un 401 si l'en-tête est mal construit. Les trois façons dont cela tourne mal, et comment voir l'en-tête que votre client a réellement envoyé.400 unsupported parameter sur un modèle de raisonnementLes modèles de raisonnement refusent des paramètres d'échantillonnage que tous les autres modèles acceptent. Lesquels retirer, pourquoi la valeur par défaut est de toute façon généralement ce que vous vouliez, et comment garder un seul chemin de code pour les deux types de modèles.Utilisation des tokens absente d'une réponse en streamingUne réponse en streaming ne contient aucun décompte de tokens à moins que vous ne le demandiez. Comment l'activer, où arrive le fragment final, et que faire quand une passerelle ne l'envoie pas.400 sur un appel d'outil : chaque tool_use a besoin de son tool_resultL'erreur apparaît un tour après la faute, et c'est ce qui la rend déroutante. La règle d'appariement, la règle d'ordre, et comment la reproduire volontairement pour la corriger une bonne fois.Le mode JSON renvoie quand même un texte impossible à analyserresponse_format contraint la forme, pas la fin. La troncature, l'absence de contrôle du schéma et le texte autour de l'objet cassent chacun l'analyse d'une manière différente.L'appel fonctionne avec curl mais pas depuis votre applicationMême clé, même URL, résultat différent. La différence tient presque toujours à quelque chose que curl ne fait pas : un proxy, une variable d'environnement périmée, une restriction d'IP ou une bibliothèque qui réécrit votre requête.SSL certificate verify failed lors d'un appel à une API IAUn échec TLS dans votre SDK alors que curl fonctionne, c'est presque toujours un proxy d'entreprise ou un antivirus qui re-signe le trafic. Pourquoi désactiver la vérification est la mauvaise solution, et les trois bonnes.socket hang up au milieu d'une réponse en streamingUn flux qui s'arrête en cours de route vous laisse avec une réponse partielle et aucune erreur du modèle. Comment distinguer une coupure réseau d'un abandon côté amont, et que faire dans chaque cas.Claude Code : API Error 400 prompt is too longL'erreur désigne la requête, mais la cause est le contexte accumulé de la session : fichiers lus, sorties d'outils et historique de conversation sont renvoyés à chaque tour. Quoi vider et quoi garder.Image en entrée refusée par un modèle de visionLes endpoints de vision refusent les images pour quatre raisons distinctes qui produisent des erreurs presque identiques. Comment les distinguer avant de vous lancer dans un réencodage.Le prompt système se comporte différemment selon les modèlesLes deux formes d'API dominantes placent les instructions système à des endroits différents. Le code écrit pour l'une se dégrade en silence sur l'autre au lieu d'échouer, ce qui est pire qu'une erreur.Bien lire un 429 : retry-after et les en-têtes de limiteLa plupart du code de relance devine. La réponse vous dit généralement exactement combien de temps attendre et quelle limite vous avez atteinte. Comment la lire, et que faire quand l'en-tête est absent.Les modèles d'un endpoint personnalisé n'apparaissent pas dans la liste du clientLes clients de bureau construisent leur liste de modèles de différentes manières, et plusieurs n'appellent jamais /v1/models. Comment savoir lequel vous avez et que faire dans chaque cas.Réponse vide avec finish_reason content_filterUne réponse vide avec content_filter comme motif de fin signifie qu'un système de sécurité l'a arrêtée. Comment la distinguer d'une troncature et d'un véritable échec, et ce que cela vous coûte.Les horodatages du journal d'utilisation ne correspondent pas au moment de l'appelUn appel qui apparaît à plusieurs heures du moment où vous l'avez fait est presque toujours une différence de fuseau horaire plutôt qu'un enregistrement perdu. Comment aligner les deux avant de signaler un problème de facturation.Facturé deux fois pour ce qui semblait être une seule requêteUn délai dépassé côté client n'arrête pas le travail déjà en cours sur le serveur. Le schéma habituel d'une double facturation accidentelle, et les deux changements qui l'évitent.