Retour au blog

DépannageGuide

Erreurs de connexion courantes et comment les corriger

Ce que signifient 401, 402, 400, 404, 413, 429 et 503 lorsque vous vous connectez à l'API CheapTokens, à quoi ressemblent les réponses et comment corriger chacune d'elles.

Par CheapTokens TeamPublié le 3 min de lecture

Liste des codes de statut HTTP 401, 402, 400, 404 et 429 avec de brèves explications dans un terminal
Sur cette page
  1. Vérification rapide
  2. 401 — Clé API invalide
  3. 402 — solde vide ou aucune clé dans la requête
  4. 404 — mauvaise adresse
  5. 400 — modèle introuvable
  6. 413 — requête trop volumineuse
  7. 429 — trop de requêtes
  8. 503 — modèle temporairement indisponible
  9. Attentes longues et délais d'expiration

Presque tous les problèmes de connexion se résument à quatre choses : l'adresse, la clé, l'ID du modèle et le solde. Commencez par la vérification rapide ci-dessous, puis trouvez votre code de statut. Les corps de réponse cités ici sont les réponses réelles de l'API (octobre 2026).

Vérification rapide#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Si la première commande échoue, la cause peut être le réseau de votre côté, une faute de frappe dans l'adresse — ou le service lui-même temporairement indisponible. Si seule la seconde échoue, cherchez son code de statut ci-dessous. Si les deux fonctionnent mais pas votre outil, comparez les réglages de l'outil avec ces deux commandes.

401 — Clé API invalide#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Les clients de style Anthropic reçoivent la même erreur dans leur format :

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Causes :

  • la clé a été copiée avec un caractère manquant, un espace ou des guillemets ;
  • la clé a été renouvelée dans le tableau de bord — l'ancienne ne fonctionne plus ;
  • une clé d'un autre service (par exemple OpenAI) est définie à la place de la clé CheapTokens ;
  • la variable d'environnement est vide dans ce terminal : echo ${#CHEAPTOKENS_API_KEY} affiche sa longueur.

Le tableau de bord n'affiche une clé qu'une seule fois. Si elle est perdue, appuyez sur Rotate pour en obtenir une nouvelle et mettez-la à jour partout où elle est utilisée.

402 — solde vide ou aucune clé dans la requête#

L'API renvoie 402 dans deux situations différentes :

  1. Le solde est épuisé. Les requêtes sont payées depuis le solde ; quand il est épuisé, la clé est mise en pause. Rechargez dans le tableau de bord et les requêtes repassent.
  2. La requête n'a aucune clé. Si l'en-tête Authorization (ou x-api-key pour les clients de style Anthropic) est absent, l'API répond 402 avec le type insufficient_funds. Vérifiez que votre outil envoie bien la clé : le style OpenAI est Authorization: Bearer <key>.

404 — mauvaise adresse#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Le chemin contient une faute de frappe — ici completion au lieu de completions. Autres causes fréquentes :

  • L'URL de base n'a pas de /v1. Les clients de style OpenAI ont besoin de https://api.cheaptokens.dev/v1. Sans /v1, la requête rate l'API et vous obtenez une simple page HTML 404 au lieu de JSON.
  • /v1 deux fois. Certains clients ajoutent /v1 eux-mêmes ; l'URL de base doit alors être la racine, https://api.cheaptokens.dev. Les clients de style Anthropic utilisent toujours l'adresse racine.

400 — modèle introuvable#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

L'ID du modèle doit être l'ID complet, préfixe avant la barre oblique inclus : deepseek-ai/DeepSeek-V4-Flash-0731, pas deepseek-v4-flash. La casse (majuscules ou minuscules) n'a pas d'importance. Le message d'erreur liste les ID disponibles, et la liste complète se trouve toujours à GET /v1/models.

Un 400 est aussi renvoyé pour un corps de requête mal formé — par exemple un tableau messages vide (messages field is required and must be a non-empty array) ou un message sans role.

413 — requête trop volumineuse#

Le corps de la requête est limité à 16 Mo. Les agents peuvent l'atteindre en mettant d'énormes fichiers ou journaux dans le contexte. N'envoyez que les parties dont le modèle a besoin et tronquez les longues sorties d'outils.

429 — trop de requêtes#

Si vous recevez 429, ralentissez. La réponse inclut un en-tête Retry-After avec le nombre de secondes à attendre. Les SDK officiels OpenAI réessaient automatiquement (max_retries) ; dans votre propre code, attendez Retry-After avant la tentative suivante.

503 — modèle temporairement indisponible#

Un modèle peut être temporairement indisponible ; l'API répond alors 503 avec le type model_unavailable, et la fiche du modèle sur le site affiche « temporairement indisponible ». Réessayez plus tard ou changez le champ model pour un autre modèle — la clé et l'adresse restent les mêmes.

Attentes longues et délais d'expiration#

Les modèles de raisonnement comme zai-org/GLM-5.3-Flash réfléchissent avant de répondre, donc le premier token peut prendre du temps. Utilisez le streaming ou augmentez le délai d'expiration du client — par exemple timeout=120 dans le SDK OpenAI.

Étiquettes: