Après avoir connecté Chatbox à une API personnalisée, les erreurs ne signifient généralement pas que « le modèle est cassé » : elles se répartissent en quatre familles — identité incorrecte, adresse ou modèle incorrect, quota ou concurrence atteints, réseau et TLS défaillants. Classer avant de vérifier est bien plus efficace que réinstaller le client en boucle.

Cet article détaille 401, 404 (y compris model not found), 429 et les échecs de connexion, puis complète avec l'interruption du streaming, la synchronisation multi-appareils et la collecte de journaux. Les noms d'interface dépendent de la version de Chatbox installée ; modèles et prix figurent sur la page tarifs des modèles.

Remarque : Chatbox est un produit et une marque de son détenteur. Cet article est purement technique et n'implique aucune affiliation ; les noms de champs et valeurs par défaut peuvent varier selon la version.

1. Conserver les preuves avant de classer

Symptôme Code ou erreur fréquente Première hypothèse À vérifier
401 Unauthorized invalid_api_key, réponse vide Clé ou en-tête de requête Clé complète, cohérence avec l'adresse
404 / model not found not_found_error Chemin ou identifiant de modèle Hôte, chemin API, identifiant
429 Too Many Requests rate_limit_error, insufficient_quota Limite de débit ou solde Usage, concurrence, facture
Failed to fetch / Network Error Aucun code Réseau injoignable DNS, proxy, pare-feu, TLS
5xx server_error Panne amont ou passerelle Réessayer et noter l'identifiant de requête

Avant tout diagnostic, notez l'heure, la version de Chatbox, le code HTTP, le corps de réponse et l'identifiant de requête. Sans ces informations, vous ne pouvez que deviner ; avec elles, vous distinguez client, réseau et serveur.

2. 401 : clé non reconnue

Un 401 signifie que le serveur ne reconnaît pas la clé. Causes fréquentes :

  • Un espace, un retour à la ligne ou un caractère pleine chasse s'est glissé à la copie : le texte semble identique, il ne l'est pas ;
  • une clé de licence Chatbox AI a été saisie comme clé API dans le fournisseur personnalisé ;
  • la clé a été supprimée ou remplacée, ou le projet est désactivé ;
  • une clé du fournisseur A est utilisée contre l'adresse du fournisseur B ;
  • la requête passe par un proxy d'entreprise qui renvoie une page de connexion 401 en HTML au lieu de JSON.

Confirmez d'abord que le mode API est « compatible OpenAI », puis recollez la clé. Ne vous fiez pas à l'apparence : testez hors du client :

export ZSQH_API_KEY="sk-votre-clé"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-ID-de-modèle","messages":[{"role":"user","content":"Réponds seulement OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Un 200 avec choices confirme la clé et l'adresse ; si le 401 persiste, le problème vient de la copie, des droits ou du proxy. Un 403 signifie plutôt « je vous reconnais, mais ce modèle n'est pas accessible avec cette clé » : ne le confondez pas avec un 401 et ne changez pas de clé en boucle.

3. 404 et model not found : vérifier adresse et modèle séparément

Un 404 a deux origines : le chemin n'existe pas, ou le modèle n'existe pas. La première se lit dans l'URL, la seconde dans l'identifiant. Chatbox sépare l'hôte API et le chemin API ; l'erreur la plus fréquente est un /v1 en double : l'hôte finit déjà par /v1 et le chemin contient encore /v1/chat/completions, ce qui donne /v1/v1/chat/completions.

Critère unique : dans l'adresse finale, /v1 ne doit apparaître qu'une fois. Si l'hôte est https://ai.zhongshangqihang.com, laissez le chemin vide ou conforme à la documentation de votre version ; si l'hôte est .../v1, ne répétez pas /v1 dans le chemin. Enregistrez, puis retestez avec « Vérifier » ou curl.

model_not_found est indépendant du chemin. L'identifiant de modèle respecte la casse, le suffixe de version et le préfixe fournisseur ; copiez-le depuis la page tarifs des modèles ou la console. En ajout manuel, vérifiez aussi que le type est « dialogue » et que les capacités cochées correspondent au modèle, sinon il peut ne pas apparaître ou échouer au premier appel.

Un échec de « Récupérer la liste des modèles » ne prouve pas une mauvaise configuration. Certaines passerelles n'exposent pas cette interface ; une saisie manuelle correcte suffit au dialogue.

4. 429 : limite de débit, concurrence et solde

Un 429 a deux sens : les requêtes vont trop vite, ou le quota est épuisé. Les interfaces compatibles OpenAI utilisent souvent rate_limit_error pour le premier et insufficient_quota pour le second. Le code est identique, le traitement est opposé.

  • Requêtes trop rapides : réduire la concurrence, fermer des sessions et clients simultanés ; un long contexte amplifie la consommation de tokens.
  • Quota épuisé : vérifier l'usage et la facture de la passerelle, recharger ou changer de clé ; réessayer ne rétablit rien.
  • Si l'en-tête Retry-After est présent, respectez-le ; sinon, backoff exponentiel avec gigue aléatoire.
  • Ne cliquez pas sur « Vérifier » ni ne renvoyez en boucle dans Chatbox : les requêtes s'empilent vite.
  • Une même clé partagée entre appareils et fenêtres partage aussi la limite de concurrence.

Si le 429 n'apparaît que dans les longues conversations, compressez le contexte ou ouvrez une nouvelle session, puis vérifiez la fenêtre de contexte du modèle. Le réglage « nombre maximal de messages de contexte » peut être abaissé, mais il ne soulage que la pression du contexte, pas la gestion de l'usage et de la concurrence.

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

Failed to fetch, Network Error ou une attente infinie signifient que la requête n'a pas obtenu de réponse valide. Vérifiez d'abord qu'un navigateur ouvre le site, puis testez le même domaine avec curl. Si curl échoue aussi, le problème est réseau ou passerelle ; si curl réussit mais Chatbox échoue, cherchez côté proxy du client, assemblage du chemin ou confiance dans le certificat.

  • Réseau d'entreprise : un pare-feu ou une passerelle de sécurité peut bloquer un domaine inconnu ; demandez à l'IT de l'autoriser.
  • Proxy : proxy système, VPN et interrupteur proxy interne à Chatbox peuvent se superposer ; ne gardez qu'une couche et ne mettez pas l'adresse du proxy dans l'hôte API.
  • TLS : self signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE ou certificat expiré apparaissent souvent avec un proxy d'inspection ; installez le certificat racine de l'entreprise plutôt que de désactiver la vérification.
  • Heure système : un écart important fait échouer la validation du certificat.
  • Réseau mobile : des résultats différents en Wi-Fi et en cellulaire indiquent un problème de réseau local ou de DNS.

Si l'erreur ne concerne qu'une machine, comparez d'abord proxy système, fichiers hosts, DNS et certificats, avant de suspecter le modèle.

6. Flux interrompu et « réponse qui s'arrête à mi-chemin »

Chatbox utilise le streaming par défaut. Une coupure en cours vient souvent de trois causes : un proxy ou la passerelle met en tampon le SSE, un timeout d'inactivité, ou une déconnexion amont en pleine génération. Le symptôme : la première moitié arrive normalement, la seconde s'arrête brutalement, ou l'interface reste sur « en train d'écrire ».

Désactivez le streaming si la version le permet et comparez avec la même question. Si le mode non streaming renvoie tout, le problème est dans la chaîne SSE ; vérifiez la mise en tampon du proxy, les timeouts et la stabilité du réseau. Les réponses longues, les modèles de raisonnement et les heures de pointe déclenchent plus facilement le phénomène ; raccourcissez la sortie ou réessayez plus tard.

Les modèles de raisonnement peuvent aussi « réfléchir » longtemps avant le texte, ce qui ressemble à un blocage. Attendez, puis confirmez avec une requête non streaming.

7. Multi-appareils, sessions et synchronisation

Les conversations et réglages de Chatbox sont par défaut stockés localement. Ne pas retrouver l'historique après un changement d'ordinateur ou de téléphone relève souvent d'une donnée non transférée, pas d'une panne API. Pour migrer, utilisez les fonctions d'export, d'import ou de sauvegarde du client ; les capacités varient selon la version.

Les versions récentes de Chatbox permettent d'importer une configuration de fournisseur au format JSON, avec hôte, liste de modèles et capacités. La clé API reste à gérer séparément : une clé par appareil ou par personne, pour ne révoquer qu'une seule en cas de fuite.

Si deux appareils se comportent différemment, comparez d'abord version, proxy système et configuration de modèle, puis la clé. Ne concluez pas du « ça marche sur l'autre » qu'il s'agit forcément d'un problème réseau local.

8. Journaux et preuves : décrire précisément le problème

Les entrées de journaux et de diagnostic varient selon la version de Chatbox : certaines proposent un export dans les paramètres, d'autres s'appuient sur les journaux système. Quoi qu'il en soit, notez manuellement :

  • l'heure (avec fuseau) et le caractère reproductible ou non ;
  • la version de Chatbox, le système et l'environnement réseau ;
  • le code HTTP et le corps complet de la réponse (clé supprimée) ;
  • l'identifiant de requête présent dans les en-têtes ;
  • le résultat curl de la même requête, et la comparaison streaming/non streaming.

Lors d'un signalement, masquez la clé mais conservez l'identifiant de modèle, l'horodatage et le code. « Ça ne se connecte pas » ne permet pas de localiser ; avec ces preuves, la plupart des problèmes se cadrent en un tour.

9. Un ordre de diagnostic fixe

  1. Interroger directement la passerelle avec curl pour valider clé, hôte et modèle.
  2. Si curl échoue : vérifier DNS, proxy, TLS, pare-feu et état de la passerelle.
  3. Si curl réussit mais Chatbox échoue : vérifier type d'API, double /v1, identifiant de modèle et proxy du client.
  4. 401 : clé ; 404 : chemin et modèle ; 429 : usage et concurrence ; échec de connexion : réseau et certificats.
  5. Ne changer qu'une variable à la fois, retester aussitôt et noter le résultat.

L'intérêt de cet ordre est de séparer « problème client » et « problème serveur ». La plupart des erreurs attribuées à Chatbox se ramènent à un réglage ou à une couche réseau.

Pour gérer clés, usage et point d'entrée des modèles de façon unifiée, vous pouvez créer un compte ZSQH AI Gateway ; les modèles disponibles et la facturation figurent sur la page tarifs des modèles, les prix pouvant évoluer, la page au moment de la commande fait foi.

Questions fréquentes

Chatbox affiche Failed to fetch : est-ce une erreur de clé ?

Pas nécessairement. Ce message indique seulement l'absence de réponse côté client ; une clé erronée n'est qu'une cause possible. Testez le même hôte avec curl ; si curl échoue aussi, cherchez réseau, proxy et certificats.

Pourquoi curl fonctionne-t-il alors que Chatbox ne se connecte pas ?

Causes fréquentes : proxy du client, double /v1, type d'API incorrect, certificat système non approuvé, ou assemblage du chemin différent selon la version. Comparez l'adresse finale de la requête, point par point.

Un 429 finit-il par se résoudre en réessayant ?

En cas de limite de débit, un backoff et une baisse de concurrence peuvent suffire ; en cas de quota épuisé, réessayer ne change rien : vérifiez la facture ou changez de clé. Lisez d'abord le type d'erreur dans le corps de réponse.

La récupération de la liste échoue : peut-on ajouter un modèle à la main ?

Oui. Certaines passerelles n'exposent pas l'interface de liste ; une saisie manuelle correcte permet le dialogue, à condition que l'identifiant, le type d'API et l'hôte soient exacts.

Les conversations et la configuration se synchronisent-elles automatiquement après un changement d'appareil ?

Les conversations sont stockées localement par défaut et ne se synchronisent pas forcément. Utilisez export et import ; les versions récentes acceptent une configuration fournisseur JSON, mais la clé API doit être ressaisie et gérée séparément.

Lectures associées :