Erreurs API Cursor : 401, 404, 429 et connexion (2026)

Dans Cursor, lorsqu'on renseigne une clé API personnalisée et une URL de base, les erreurs se répartissent généralement en quatre couches : les identifiants, le chemin, la limitation de débit et le réseau. Beaucoup d'utilisateurs changent de modèle dès qu'un message rouge apparaît, et transforment ainsi un problème de configuration en une demi-journée perdue. Le bon ordre consiste à lire d'abord le code de statut, à reproduire ensuite avec une requête minimale, et à ne modifier le modèle ou le prompt qu'en dernier recours.

Cet article traite séparément les cas 401, 404, 429, les échecs de connexion, les interruptions de flux et le dépassement de contexte. Il fournit des commandes de diagnostic, les champs à journaliser et une liste de vérification utilisable par le support.

Remarque : Cursor est une marque d'Anysphere, Inc. Les versions de Cursor évoluent vite et les menus comme les messages d'erreur peuvent changer ; cet article se fonde sur les versions courantes d'octobre 2026. Votre version actuelle et la documentation officielle font foi.

1. Ordre de diagnostic : isoler la couche avant de modifier la configuration

Code / symptôme	Signification courante	À vérifier en premier	Faut-il réessayer
401	Clé absente, erronée, expirée ou sans droit	Clé, champ d'authentification, état du compte	Non
403	Clé sans droit sur le modèle ou politique d'équipe	Droits sur le modèle, réglages d'équipe	Non
404	Chemin incorrect ou modèle inexistant	URL de base, ID du modèle	Non
429	Fréquence, concurrence ou quota de jetons dépassé	Consommation, clé partagée, stratégie de reprise	Oui, après temporisation
400/413	Format de requête ou contexte trop long	Contexte, paramètres, max_tokens	Oui, après correction
5xx	Erreur serveur ou passerelle surchargée	État du service, ID de requête	Oui, après temporisation
Échec de connexion	DNS, TLS, proxy, pare-feu	Chaîne réseau	Oui, après réparation

Fixez d'abord une seule variable : même clé, même URL de base, même ID de modèle. Ne changez qu'un élément à la fois. Si vous modifiez trois réglages simultanément, un succès ne vous dira pas lequel était en cause.

2. 401 : vérifier la clé, puis le champ d'authentification

Un 401 signifie que l'identité n'a pas été validée ; cela n'a aucun rapport avec les capacités du modèle ni avec la longueur du contexte. Procédez dans cet ordre :

Vérifiez que la clé a été copiée en entier, sans espace, saut de ligne ni guillemet avant ou après. Une copie depuis une fenêtre de discussion contient souvent des caractères invisibles.
Vérifiez que la clé est saisie dans le bon champ du fournisseur. Dans Cursor, OpenAI, Anthropic, Google et Azure disposent de champs distincts ; un mauvais champ provoque directement un 401.
Vérifiez que la clé n'a pas été supprimée, désactivée ou qu'elle n'a pas expiré. Consultez son état dans la console de la passerelle, pas seulement dans un fichier local.
Vérifiez que le compte dispose d'un solde ou d'un quota. Certaines passerelles renvoient 401 ou 403 en cas de solde insuffisant ; lisez le corps de la réponse.
Vérifiez que l'équipe n'interdit pas les clés tierces personnelles. Les offres Teams/Enterprise de Cursor peuvent bloquer le BYOK côté administration ; dans ce cas, une configuration locale correcte échouera quand même.
Vérifiez que l'URL de base correspond à l'environnement de la clé. Une clé de test pointée vers l'adresse de production renvoie généralement un 401.
Vérifiez que les variables d'environnement sont réellement chargées. N'affichez que les quatre premiers et quatre derniers caractères de la clé ; n'écrivez jamais la clé complète dans un journal.

# Test d'authentification minimal : valider l'adresse, la clé et le protocole
export API_KEY="sk-votre-cle"

curl -sS -o /tmp/cursor_resp.json -w "%{http_code}\n" \
  "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

cat /tmp/cursor_resp.json

Une réponse 200 indique que la clé et l'adresse fonctionnent globalement. Si vous obtenez 401, testez la même clé dans l'entrée de test de la console de la passerelle : vous saurez si le problème vient de la clé elle-même ou du champ et de la couche réseau de Cursor.

3. 404 : URL de base et ID de modèle à parts égales

Un 404 ne signifie pas forcément que le modèle a été retiré. La cause la plus fréquente est une URL mal construite :

L'URL de base omet /v1 : la requête atteint une route web du site et reçoit du HTML ou un 404.
L'URL de base contient déjà /v1/chat/completions, et le client ajoute une seconde fois le chemin, ce qui donne /v1/chat/completions/chat/completions.
Le chemin Anthropic /v1/messages est saisi dans un champ compatible OpenAI, ou l'inverse.
Le nom de domaine est incorrect, ou l'adresse de la console est utilisée à la place de l'adresse API.

L'ID de modèle peut aussi provoquer un 404 ou un model_not_found :

La casse, les tirets et le numéro de version doivent correspondre exactement à la page tarifs ou à la liste des modèles.
Le modèle peut ne pas être ouvert au compte ou à l'offre actuelle.
Un même modèle peut avoir des ID différents selon le protocole.
Le bouton Verify de Cursor teste généralement la clé et l'adresse, pas la validité de l'ID de modèle ; confirmez par une requête réelle.

Pour diagnostiquer, consultez d'abord /v1/models si la passerelle l'expose, puis copiez l'ID depuis la liste retournée. Ne le saisissez pas à la main.

4. 429 : une limitation de débit, pas un solde insuffisant

Un 429 indique que la requête dépasse la limite de fréquence, de concurrence ou de quota de jetons. Les déclencheurs courants sont :

Nombre de requêtes par minute ou de jetons par minute dépassé.
Plusieurs personnes partagent une même clé et se disputent le quota.
Un agent lit des fichiers et exécute des commandes en continu, ce qui envoie beaucoup de requêtes en peu de temps.
Les reprises n'appliquent aucune temporisation : plus l'échec est fréquent, plus les requêtes partent, jusqu'à la tempête de reprises.
Les requêtes à contexte long consomment davantage de quota et réduisent la marge disponible pour la concurrence.

Lisez d'abord les en-têtes et le corps de la réponse ; n'augmentez pas les reprises à l'aveugle. Si un Retry-After est présent, attendez la durée indiquée ; sinon, appliquez un backoff exponentiel avec une gigue aléatoire. Ne réessayez pas les 401 et les 404 : cela ne fait qu'aggraver le diagnostic.

import random
import time

def retry_delay(attempt, base=1.0, cap=30.0):
    delay = min(cap, base * (2 ** attempt))
    return delay + random.uniform(0, delay * 0.3)

for attempt in range(4):
    response = send_request()  # remplacez par votre fonction de requête
    if response.status_code not in (429, 500, 502, 503, 504):
        break
    time.sleep(retry_delay(attempt))

Si les 429 se concentrent sur une plage horaire fixe, mettez en place une file d'attente et un lissage de l'envoi. Si une seule clé sert plusieurs services, séparez les clés par projet. Si le problème vient d'une boucle d'agent, fixez-lui un nombre maximal de tours et un plafond de quota.

5. Échec de connexion : SSL, proxy et DNS

Un échec de connexion ne renvoie généralement pas de code HTTP : délai d'attente, ECONNRESET, erreur de certificat ou message « impossible de se connecter au serveur ». Ordre de diagnostic :

Utilisez curl -Iv pour voir où s'arrêtent la résolution DNS, la connexion TCP et la poignée de main TLS.
Vérifiez si le certificat est expiré, auto-signé ou remplacé par le réseau de l'entreprise. Lorsqu'un proxy d'entreprise inspecte TLS, le certificat racine de l'entreprise doit être installé dans la chaîne de confiance du système.
Vérifiez si les variables de proxy ne s'appliquent qu'au terminal et si Cursor lui-même ne passe pas par le proxy. Contrôlez les réglages réseau/proxy de Cursor et comparez connexion directe et proxy si nécessaire.
Vérifiez si un VPN, un pare-feu ou un logiciel de sécurité bloque les connexions longues ou les réponses en flux.
Vérifiez l'heure système. Un écart important fait échouer la validation du certificat.
Vérifiez si HTTP/2 ou la réutilisation de connexion est perturbée par un équipement intermédiaire. Testez d'abord une requête courte et non streamée.

N'utilisez pas « le ping passe » comme preuve que l'API fonctionne. Le ping prouve seulement que l'hôte est joignable, pas que TLS, le certificat et le chemin sont corrects.

6. Flux interrompu et contexte dépassé

Une sortie en flux s'interrompt souvent dans trois cas : le proxy met en tampon les événements SSE, la connexion dépasse le délai d'inactivité, ou le modèle est limité pendant la génération. Le symptôme est une réponse qui s'arrête à mi-chemin, un message stream ended unexpectedly, ou Cursor qui tourne indéfiniment.

Méthode de diagnostic :

Envoyez la même requête avec "stream": false. Si le mode non streamé passe, le problème vient de la chaîne de flux ou du proxy.
Testez en direct avec curl -N pour écarter le client Cursor.
Réduisez max_tokens et la longueur du contexte pour voir si l'interruption persiste.
Vérifiez si le proxy active la mise en tampon des réponses ; si nécessaire, faites passer le domaine de l'API en connexion directe.
Pour les tâches d'agent longues, fixez un délai maximal et un nombre de tours maximal afin d'éviter une connexion bloquée.

Un dépassement de contexte renvoie généralement 400 ou 413, avec des mentions comme context_length_exceeded ou maximum context length dans le corps de l'erreur. Cursor envoie ensemble les fichiers ouverts, les extraits recherchés et l'historique de conversation ; le contexte réel est souvent plus long que prévu. Pour corriger : excluez les artefacts de build et les journaux via les fichiers ignorés, fermez les onglets inutiles, résumez les documents longs et ouvrez une nouvelle session pour les conversations longues.

7. Quels journaux conserver pour le support

Consignez au minimum : horodatage, code de statut, code d'erreur, ID de modèle, nom d'hôte de l'URL de base, ID de requête, durée et nombre de reprises. L'ID de requête se trouve souvent dans les en-têtes de réponse, sous un nom comme request-id, x-request-id ou x-oneapi-request-id ; référez-vous à ce que la passerelle renvoie réellement.

Une entrée de journal exploitable ressemble à ceci :

2026-10-19T10:12:33+08:00 status=429 code=rate_limit_exceeded model=votre-modele host=api.zhongshangqihang.com request_id=... latency_ms=1840 retry=2

Ne journalisez pas la clé complète, les prompts complets ni le code utilisateur. Conservez seulement les quatre premiers et quatre derniers caractères de la clé et masquez les contenus sensibles. Pour le support, un journal avec un ID de requête est plus utile que dix captures d'écran.

8. Liste de vérification pour le support

Notez le message d'erreur exact, le code de statut, l'heure et l'ID de requête.
Reproduisez la même requête avec curl pour vérifier si le problème n'apparaît que dans Cursor.
Vérifiez l'URL de base : compatible OpenAI s'arrête généralement à /v1, Claude Code utilise l'adresse racine.
Vérifiez l'ID de modèle : copiez-le depuis la liste, contrôlez la casse et la version.
Testez avec une nouvelle clé pour écarter une clé invalide, un quota épuisé ou une politique d'équipe.
Commencez par une requête courte et non streamée, puis réintroduisez le flux et le contexte long progressivement.
Changez de réseau ou de proxy pour écarter DNS, TLS et proxy d'entreprise.
Si tout ce qui précède passe, transmettez les journaux et les étapes de reproduction au support de la passerelle ou de Cursor.

9. Questions fréquentes

La clé fonctionne ailleurs, mais Cursor renvoie 401 ?

Vérifiez d'abord le champ du fournisseur, puis si l'URL de base correspond à l'environnement de la clé. En offre équipe, confirmez aussi que l'administrateur n'a pas interdit les clés tierces personnelles.

Un 404 signifie-t-il toujours que le modèle a été retiré ?

Non. Le plus souvent, l'URL de base a un /v1 en trop ou en moins, ou l'ID de modèle est mal orthographié. Consultez la liste des modèles et copiez l'ID avant de tester.

Un 429 correspond-il à un solde insuffisant ?

Pas nécessairement. Un 429 indique un dépassement de fréquence ou de quota ; un solde insuffisant peut renvoyer 401, 402 ou 403 selon la passerelle. Fiez-vous au corps de l'erreur et à la page de facturation.

Peut-on utiliser directement les modèles Claude dans Cursor ?

Oui, via une clé Anthropic ou via le protocole OpenAI d'une passerelle compatible. Dans les versions courantes, le champ Anthropic ne permet pas de remplacer l'URL de base ; pour une passerelle, choisissez généralement OpenAI Compatible et saisissez l'ID de modèle exact.

Pourquoi seules les requêtes en flux échouent-elles ?

Soupçonnez d'abord la mise en tampon du proxy, le délai d'inactivité et la réutilisation de connexion. Comparez avec une requête non streamée, puis testez en direct avec curl -N : vous identifierez généralement le segment fautif.

Étape suivante

Créez d'abord une clé de test sur ZSQH AI Gateway, exécutez les commandes curl de cet article pour valider l'authentification, le modèle et le flux, puis renseignez Cursor. La disponibilité des modèles et les tarifs figurent sur la page Tarifs des modèles. Pour le diagnostic, fixez les variables puis remplacez-les une par une.

Pour aller plus loin :

Remarque : Cursor est une marque d'Anysphere, Inc. ; OpenAI, Anthropic, Claude et Google sont des marques de leurs détenteurs respectifs. Cet article est purement technique et n'implique aucun lien d'affiliation avec ces sociétés. Les messages, menus et comportements d'interface peuvent évoluer ; la documentation officielle fait foi.