> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Diagnostiquez les erreurs API BetterToken avec le statut HTTP, la réponse et l’ID de requête. Corrigez l’authentification, les limites et les délais d’attente.

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](https://bettertoken.ai/workspace). Si vous n’avez encore réussi aucune requête à un modèle, commencez par les [exemples de SDK](/fr/guides/sdk-examples.md) ou le [guide de configuration de votre outil](/fr/ai-tools/overview.md).

## Lire la réponse d’erreur

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

```json theme={null}
{
  "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](/fr/faq/codex/usage-limit-vs-api-rate-limit.md) | 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](/fr/faq/model-calling/base-url-config.md). Pour le cache, consultez la [FAQ sur la facturation du cache](/fr/faq/service-assurance/cache-billing.md).

## 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](https://bettertoken.ai/pricing) et remplacez les deux valeurs d’exemple. Utilisez un modèle de texte disponible via [Chat Completions](/fr/api-reference/chat-completions.md).

```bash theme={null}
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**

```python theme={null}
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)
```

**JavaScript**

```javascript theme={null}
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](/fr/ai-tools/claude-code.md#common-errors) |
| Codex demande une connexion ou ignore les changements de fournisseur | [Erreurs fréquentes de Codex CLI / App](/fr/ai-tools/codex.md#common-errors) |
| Impossible d’activer la Key de Cursor ou les modèles intégrés ne fonctionnent plus | [Erreurs fréquentes de Cursor](/fr/ai-tools/cursor.md#common-errors) |
| Erreur d’authentification, `404` ou de modèle dans Cline | [Erreurs fréquentes de Cline](/fr/ai-tools/cline.md#common-errors) |
| Erreur de fournisseur, de modèle ou de configuration de projet dans OpenCode | [Erreurs fréquentes d’OpenCode](/fr/ai-tools/opencode.md#common-errors) |
| Le Gateway de Claude Desktop ne se connecte pas | [Erreurs fréquentes de Claude Desktop](/fr/faq/claude-desktop-bettertoken-api.md#common-errors) |
| Avertissement d’utilisation du Codex officiel ou `429` de l’API | [Limite d’utilisation et limite de débit API](/fr/faq/codex/usage-limit-vs-api-rate-limit.md) |
| Les modifications semblent sans effet | [Effacer les variables d’environnement en conflit](/fr/best-practices.md#clear-conflicting-environment-variables) |
| Sortie tronquée ou erreur de limite de sortie | [Limites de tokens de sortie](/fr/faq/model-calling/max-tokens.md) |

## 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](/fr/faq/codex/usage-limit-vs-api-rate-limit.md) 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](/fr/best-practices.md#set-a-generous-timeout), puis vérifiez avec une petite requête.

## Ressources associées

* [Exemples de requêtes avec les SDK](/fr/guides/sdk-examples.md)
* [Streaming et appels d’outils](/fr/guides/streaming-and-tool-calling.md)
* [Référence API](/fr/api-reference/introduction.md)
* [Outils compatibles](/fr/ai-tools/overview.md)
* [FAQ sur la facturation du cache](/fr/faq/service-assurance/cache-billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.