Erreurs API BetterToken : codes HTTP et limites de requêtes

Diagnostiquez une erreur API BetterToken en combinant le statut HTTP et le corps de la réponse. Relevez l’ID de requête dans error.message, corrigez les erreurs d’authentification ou de configuration avant de renvoyer la requête et ne relancez que les échecs identifiés comme temporaires.

Avant le diagnostic

Gardez à portée de main votre Model ID, votre Base URL et la réponse en erreur. Vérifiez l’état de la Key et le solde actuel dans le Dashboard BetterToken. Si vous n’avez encore réussi aucune requête à un modèle, commencez par les exemples de SDK ou le guide de configuration de votre outil.

Lire la réponse d’erreur

BetterToken renvoie les erreurs API dans une structure JSON. Par exemple, une requête sans Key peut renvoyer :

{
  "error": {
    "code": "",
    "message": "Token not provided (request id: …)",
    "type": "new_api_error"
  }
}

Lisez error.message même si error.code est vide. L’ID de requête dans ce message aide à identifier la tentative en échec. Une requête à /v1/models sans Key renvoie 401 ; elle ne vérifie pas si votre modèle peut générer une réponse. Relevez ces informations avant de contacter le support :

Information	Données à relever
Statut HTTP	Statut de la réponse, ou exception réseau ou délai d’attente du client si aucune réponse HTTP n’est arrivée
Corps de la réponse	JSON d’erreur ou autre contenu renvoyé, sans données secrètes
ID de requête	Identifiant dans `error.message`, s’il est présent
Heure	Date, heure et fuseau horaire de la tentative
Model ID	Valeur exacte envoyée comme `model`
Base URL	Base URL configurée et chemin final de la requête

N’incluez pas votre BetterToken API Key dans les captures d’écran, les messages au support ou les journaux partagés.

Vérifier le statut HTTP

Le tableau reprend les significations générales HTTP et API ainsi que les guides de configuration liés. Il ne s’agit pas d’une liste de codes propres à BetterToken ; lisez la réponse réelle avant de choisir une correction.

Statut	Signification courante	À vérifier en premier	Relancer ?
`400`	Requête, champ ou combinaison de paramètres invalides	Structure JSON, champs requis, modèle et spécification de l’endpoint	Corrigez d’abord la requête
`401`	Identifiant absent, invalide, expiré ou révoqué	État de la Key, espaces et en-tête d’authentification du protocole	Corrigez d’abord l’authentification
`403`	Requête refusée	Message de réponse, solde, état de la Key et configuration du client	Résolvez d’abord le refus
`404`	Route ou ressource demandée introuvable	Base URL, `/v1` absent ou en double, chemin final et Model ID exact	Corrigez d’abord l’URL ou la ressource
`408` / délai d’attente du client	Le serveur n’a pas reçu la requête complète à temps ou le client a cessé d’attendre	Réception d’un statut HTTP, délais configurés, réseau et état de la requête dans le Dashboard	Vérifiez si la requête s’est terminée avant de décider
`409` / `422`, s’ils sont renvoyés	Généralement un conflit ou un contenu impossible à traiter	Détails de la réponse et état ou champs envoyés	Résolvez d’abord la cause
`429`	Une limite a été atteinte	Corps de la réponse et en-têtes de nouvelle tentative ; consultez la FAQ de diagnostic des limites	Seulement si une limite temporaire de débit est identifiée
`500`	Échec côté serveur	Enregistrement de la requête, message et persistance de l’échec	Tentatives bornées pour un échec temporaire
`502` / `503`	Échec de passerelle ou du service en amont, ou indisponibilité temporaire	Corps de la réponse et éventuel en-tête `Retry-After`	Tentatives bornées pour un échec temporaire
`504`	La passerelle a dépassé le délai d’attente d’une réponse en amont	Enregistrement dans le Dashboard et achèvement de la requête	Vérifiez l’achèvement avant de relancer

Pour les erreurs de protocole ou de suffixe, consultez la FAQ Base URL. Pour le cache, consultez la FAQ sur la facturation du cache.

Relancer les échecs temporaires

Après avoir identifié un 429 temporaire ou un échec temporaire du serveur, utilisez une attente exponentielle bornée avec une variation aléatoire. Respectez Retry-After s’il est renvoyé ; s’il dépasse votre budget de relance, arrêtez la boucle et attendez en dehors. Les relances du SDK et de votre boucle partagent le même nombre maximal de tentatives ; désactivez celles du SDK si vous définissez votre propre politique. Ne relancez pas à l’identique les erreurs 400, 401, 403, de solde ou de configuration. Un délai d’attente dépassé ou un flux interrompu ne prouve pas que la requête a échoué avant son traitement. Vérifiez d’abord le Dashboard, surtout pour la génération d’images ou un workflow susceptible de répéter une action. Les exemples suivants envoient une requête Chat Completions sans streaming, avec quatre tentatives au maximum. Ils relancent les statuts HTTP 500, 502 et 503. Les relances de 429 restent désactivées tant que vous n’avez pas confirmé une limite temporaire de débit. Les exemples s’arrêtent en cas de délai dépassé, d’exception réseau ou de 504 pour vous permettre de vérifier l’achèvement. L’attente maximale est de 30 secondes par relance.

Préparer la requête

Copiez un Model ID actuel depuis la model plaza et remplacez les deux valeurs d’exemple. Utilisez un modèle de texte disponible via Chat Completions.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
export BETTERTOKEN_MODEL_ID="YOUR_MODEL_ID"

L’exemple Python utilise la bibliothèque standard. Enregistrez l’exemple JavaScript dans un fichier .mjs et exécutez-le avec une version de Node.js proposant fetch et AbortSignal.timeout.

Python
JavaScript

import json
import os
import random
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime

def retry_after_seconds(value):
    try:
        return max(0.0, float(value))
    except ValueError:
        return max(0.0, (
            parsedate_to_datetime(value) - datetime.now(timezone.utc)
        ).total_seconds())

retry_temporary_429 = False  # Enable only after diagnosing the returned limit.
payload = json.dumps({
    "model": os.environ["BETTERTOKEN_MODEL_ID"],
    "messages": [{"role": "user", "content": "Reply with one word: OK"}],
}).encode()
for attempt in range(4):
    request = urllib.request.Request(
        "https://bettertoken.ai/v1/chat/completions", data=payload,
        headers={
            "Authorization": "Bearer " + os.environ["BETTERTOKEN_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            print(json.load(response)["choices"][0]["message"]["content"])
        break
    except urllib.error.HTTPError as error:
        body = error.read().decode("utf-8", errors="replace")
        retryable = error.code in (500, 502, 503) or (
            error.code == 429 and retry_temporary_429
        )
        if not retryable or attempt == 3:
            raise RuntimeError(f"HTTP {error.code}: {body}") from error
        delay = random.uniform(0, min(8.0, 2.0 ** attempt))
        retry_after = error.headers.get("Retry-After")
        if retry_after:
            delay = max(delay, retry_after_seconds(retry_after))
        if delay > 30:
            raise RuntimeError("Retry-After exceeds this retry budget") from error
        time.sleep(delay)

const retryTemporary429 = false; // Enable only after diagnosing the returned limit.
const payload = {
  model: process.env.BETTERTOKEN_MODEL_ID,
  messages: [{ role: "user", content: "Reply with one word: OK" }],
};
for (let attempt = 0; attempt < 4; attempt++) {
  const response = await fetch("https://bettertoken.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BETTERTOKEN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(120000),
  });
  const body = await response.text();
  if (response.ok) {
    console.log(JSON.parse(body).choices[0].message.content);
    break;
  }
  const retryable = [500, 502, 503].includes(response.status) ||
    (response.status === 429 && retryTemporary429);
  if (!retryable || attempt === 3) {
    throw new Error(`HTTP ${response.status}: ${body}`);
  }
  let delay = Math.random() * Math.min(8000, 1000 * 2 ** attempt);
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter !== null) {
    const seconds = Number(retryAfter);
    const wait = Number.isFinite(seconds)
      ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (!Number.isFinite(wait)) throw new Error("Invalid Retry-After header");
    delay = Math.max(delay, wait, 0);
  }
  if (delay > 30000) throw new Error("Retry-After exceeds this retry budget");
  await new Promise(resolve => setTimeout(resolve, delay));
}

Si le corps de la réponse indique un problème persistant de configuration, de solde ou d’accès, arrêtez la boucle et corrigez-le, même si le statut seul semble autoriser une relance. Avant d’utiliser ce court exemple de texte pour d’autres opérations, adaptez-le aux vérifications d’achèvement de votre application.

Trouver le guide adapté au symptôme

Symptôme	Guide
Erreur d’authentification, d’URL ou de modèle dans Claude Code	Erreurs fréquentes de Claude Code
Codex demande une connexion ou ignore les changements de fournisseur	Erreurs fréquentes de Codex CLI / App
Impossible d’activer la Key de Cursor ou les modèles intégrés ne fonctionnent plus	Erreurs fréquentes de Cursor
Erreur d’authentification, `404` ou de modèle dans Cline	Erreurs fréquentes de Cline
Erreur de fournisseur, de modèle ou de configuration de projet dans OpenCode	Erreurs fréquentes d’OpenCode
Le Gateway de Claude Desktop ne se connecte pas	Erreurs fréquentes de Claude Desktop
Avertissement d’utilisation du Codex officiel ou `429` de l’API	Limite d’utilisation et limite de débit API
Les modifications semblent sans effet	Effacer les variables d’environnement en conflit
Sortie tronquée ou erreur de limite de sortie	Limites de tokens de sortie

Confirmer la correction

Envoyez une courte requête non critique avec le même client, la même Base URL et le même Model ID qu’en cas d’échec. Vérifiez que la réponse est normale, puis retrouvez l’enregistrement correspondant dans le Dashboard. Contrôlez le modèle, le statut, les tokens utilisés et le montant facturé avant de reprendre un workflow plus important.

Questions fréquentes

Chaque erreur 429 impose-t-elle d’attendre et de réessayer ?

Consultez la FAQ de diagnostic des limites d’utilisation pour déterminer les points à vérifier et si une relance convient à votre réponse.

Faut-il augmenter le délai d’attente après un échec ?

Vérifiez d’abord si le client, un proxy ou une requête en amont a cessé d’attendre. Utilisez les conseils sur les délais d’attente, puis vérifiez avec une petite requête.

Référence de l'API

Guides de développement

Erreurs API BetterToken : codes HTTP et limites de requêtes

Avant le diagnostic

Lire la réponse d’erreur

Vérifier le statut HTTP

Relancer les échecs temporaires

Préparer la requête

Trouver le guide adapté au symptôme

Confirmer la correction

Questions fréquentes

Chaque erreur 429 impose-t-elle d’attendre et de réessayer ?

Faut-il augmenter le délai d’attente après un échec ?

Ressources associées

​Avant le diagnostic

​Lire la réponse d’erreur

​Vérifier le statut HTTP

​Relancer les échecs temporaires

​Préparer la requête

​Trouver le guide adapté au symptôme

​Confirmer la correction

​Questions fréquentes

​Chaque erreur 429 impose-t-elle d’attendre et de réessayer ?

​Faut-il augmenter le délai d’attente après un échec ?

​Ressources associées

Avant le diagnostic

Lire la réponse d’erreur

Vérifier le statut HTTP

Relancer les échecs temporaires

Préparer la requête

Trouver le guide adapté au symptôme

Confirmer la correction

Questions fréquentes

Chaque erreur 429 impose-t-elle d’attendre et de réessayer ?

Faut-il augmenter le délai d’attente après un échec ?

Ressources associées