Qu’est-ce qu’une Base URL ? Structure d’API et erreurs 401/404

Si l’API Key existe déjà mais que le client renvoie 401, 404, 405, model not found, ouvre une page de connexion ou retourne du HTML au lieu de JSON, ne changez pas simultanément la clé, le modèle et l’adresse. Commencez par comprendre ce qu’est la Base URL, puis vérifiez la configuration dans cet ordre : protocole → adresse racine → version d’API → endpoint → authentification → modèle.

Une Base URL est l’adresse racine d’un serveur ou d’une passerelle API. Une bibliothèque cliente, un SDK ou un outil en ligne de commande lui ajoute le chemin d’une ressource précise — l’endpoint — afin de former l’URL complète de la requête.

Les exemples s’appuient sur BetterToken, mais la méthode vaut aussi pour d’autres passerelles, des proxies auto-hébergés et des services compatibles avec les protocoles OpenAI ou Anthropic.

Qu’est-ce qu’une Base URL dans une API ?

La formule la plus simple est :

URL complète de la requête = Base URL + chemin de l’endpoint

Exemple d’une requête compatible OpenAI :

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /responses
URL complète: https://www.bettertoken.ai/v1/responses

Autre endpoint courant : /chat/completions.

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /chat/completions
URL complète: https://www.bettertoken.ai/v1/chat/completions

Dans une application réelle, le client normalise généralement la barre oblique entre les deux parties. La vraie question n’est pas de savoir comment concaténer les chaînes à la main, mais si le champ Base URL contient déjà un chemin que le client ajoutera une seconde fois.

Les éléments d’une URL d’API

Prenons https://www.bettertoken.ai/v1/responses :

Élément	Exemple	Rôle
Schéma	https://	Définit le mode de connexion
Hôte	bettertoken.ai	Identifie le service API
Chemin de base	/v1	Sélectionne une version ou une entrée commune
Endpoint	/responses	Sélectionne une ressource ou une opération

Pour certains services, la Base URL ne contient que le schéma et le domaine. Pour d’autres, elle inclut aussi un chemin comme /v1. Il n’existe pas de suffixe universel : suivez la documentation actuelle du service et du client.

Ce qu’une Base URL n’est pas

Élément souvent confondu	Différence
Page d’accueil du site	Elle peut renvoyer du HTML ; une Base URL d’API sert aux requêtes programmatiques
URL complète	Elle contient déjà un endpoint tel que /responses, /chat/completions ou /v1/messages
API Key	La clé authentifie ; la Base URL détermine la destination
Model ID	Il choisit le modèle, mais pas le protocole ni la route
Adresse d’un serveur MCP	MCP connecte des outils et des données ; il ne remplace pas la Base URL du modèle

Le fait qu’une adresse s’ouvre dans un navigateur ne prouve donc pas qu’il s’agit de la bonne Base URL. De nombreuses racines d’API valides n’affichent aucune page lisible. À l’inverse, une page de connexion peut appartenir au site web et non à l’API.

Choisissez l’adresse selon le protocole du client, pas selon le nom du modèle

Une même passerelle peut proposer une entrée compatible OpenAI et une autre compatible Anthropic. Le protocole attendu par le client compte davantage que le nom GPT, Claude, Kimi ou GLM du modèle.

La documentation actuelle de BetterToken suit ces règles :

Client ou usage	Protocole habituel	Base URL à saisir	Chemin ajouté par le client
Codex	OpenAI Responses	https://www.bettertoken.ai/v1	/responses
Cursor, Cline, OpenCode et outils similaires	OpenAI-compatible	https://www.bettertoken.ai/v1	L’endpoint nécessaire, par exemple /chat/completions
Claude Code	Anthropic-compatible	https://bettertoken.ai	/v1/messages
Requête HTTP écrite manuellement	Dépend du format	Adresse du protocole choisi	Endpoint indiqué explicitement dans le code

Consultez API compatible OpenAI et API compatible Anthropic. Ne configurez pas toutes les applications avec l’adresse Anthropic sous prétexte d’utiliser un modèle Claude. De même, un modèle GPT ne permet pas d’ignorer le protocole exigé par le client.

Cinq vérifications de la Base URL

Ne changez qu’un paramètre à la fois et répétez la même requête courte après chaque modification. Vous pourrez ainsi identifier la couche responsable.

1. Confirmez le protocole attendu par le client

Vérifiez le provider ou le type d’API dans l’outil :

• Codex utilise OpenAI Responses.
• Cursor, Cline, OpenCode et de nombreux outils similaires utilisent généralement un provider OpenAI-compatible.
• Claude Code utilise le protocole Messages compatible Anthropic.
• Dans un script personnel, le format implémenté dans le code détermine le protocole.

Changer de modèle ne corrige pas une incompatibilité de protocole. Les champs de requête, l’authentification et les chemins peuvent tous différer.

2. Saisissez uniquement l’adresse racine, pas un endpoint complet

Un champ nommé base_url, Base URL, API base ou endpoint base attend généralement la racine commune.

Correct :

https://www.bettertoken.ai/v1

Erreurs fréquentes :

https://www.bettertoken.ai/v1/responses
https://www.bettertoken.ai/v1/chat/completions

Si le client ajoute /responses, la première erreur peut produire :

https://www.bettertoken.ai/v1/responses/responses

Dans Claude Code, ne placez pas non plus https://www.bettertoken.ai/v1/messages dans ANTHROPIC_BASE_URL : le programme ajoute lui-même /v1/messages.

3. Vérifiez que /v1 apparaît exactement une fois

La Base URL BetterToken destinée aux clients OpenAI-compatible contient déjà /v1. Si le SDK propose aussi api_version, path_prefix ou un champ similaire, n’ajoutez pas un second /v1 sauf exigence explicite de sa documentation.

Cette URL dans les logs indique presque toujours une mauvaise concaténation :

https://www.bettertoken.ai/v1/v1/responses

À l’inverse, une requête OpenAI-compatible sans /v1 peut renvoyer 404, le HTML du site ou une redirection vers la connexion.

4. Testez l’endpoint avec la requête la plus simple

Désactivez streaming, tools, MCP et le contexte long. Envoyez une seule phrase courte avec le même client. Ne commencez pas par une tâche capable d’écrire dans un dépôt réel.

Lancez Codex :

codex

Puis saisissez :

Réponds par une seule phrase courte : la connexion fonctionne.

Lancez Claude Code :

claude

Puis saisissez :

Réponds par une seule phrase courte : la connexion fonctionne.

Pour une requête HTTP directe, utilisez un Model ID actuellement disponible dans Setup ou Model Plaza. Le guide Codex en vigueur utilise gpt-6-astra comme exemple, mais la disponibilité réelle pour votre clé doit être vérifiée dans le tableau de bord. Réactivez streaming, tools ou les longues tâches seulement après la réussite du test minimal.

5. Redémarrez complètement le client

De nombreuses CLI, applications de bureau et extensions ne lisent les variables d’environnement et les fichiers de configuration qu’au démarrage. Enregistrer le fichier ne signifie pas que le processus en cours a chargé la nouvelle valeur.

Après une modification :

1. Fermez la CLI, l’application ou la fenêtre de l’éditeur.
2. Vérifiez que les processus associés sont terminés.
3. Ouvrez un nouveau terminal ou relancez l’application.
4. Répétez la même requête courte.

Sinon, vous pouvez regarder le nouveau fichier tout en testant encore l’ancienne Base URL.

Comment interpréter les erreurs courantes

Symptôme	Première vérification	Étape suivante
404 Not Found	/v1 dupliqué, endpoint répété, protocole incompatible	Comparez l’URL réelle des logs à la documentation
HTML ou page de connexion	Route web utilisée à la place de l’API	Vérifiez l’hôte, /v1 et l’endpoint
401	API Key, variable d’authentification, configuration active	Retirez les espaces autour de la clé et redémarrez
403	Droit de la clé sur le modèle ou la route	Vérifiez la disponibilité dans Setup ou le Dashboard
405 Method Not Allowed	Méthode HTTP et endpoint	Confirmez si la route exige POST ou une autre méthode
model not found	Base URL et protocole avant le Model ID	Ne masquez pas une erreur de routage en changeant de modèle
Timeout ou stream interrompu	Requête courte sans streaming	Si elle réussit, contrôlez streaming et timeout séparément
Aucun changement après édition	Emplacement du fichier, variables prioritaires, processus	Fermez tout puis relancez

Un 401 ne prouve pas que l’URL est correcte, et un 404 ne prouve pas que le modèle est absent. Le code d’état décrit seulement la réaction du serveur à la requête reçue.

Vérification rapide pour Codex et Claude Code

Codex

La partie de la configuration Codex liée à l’adresse doit ressembler à ceci :

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true

L’API Key est stockée dans auth.json, dans le même répertoire de configuration. Consultez le guide Codex complet pour les autres champs et les règles d’authentification. Codex ajoute /responses, ne l’incluez donc pas dans base_url.

Claude Code

Les variables principales sont :

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://bettertoken.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

Cet extrait ne met en avant que l’adresse et l’authentification. Utilisez la configuration complète du guide Claude Code. N’ajoutez ni /v1 ni /messages à ANTHROPIC_BASE_URL.

Quatre erreurs courantes de composition d’URL

Incorrect : https://www.bettertoken.ai/v1/v1/responses
Cause :     la Base URL et le client ont tous deux ajouté /v1

Incorrect : https://www.bettertoken.ai/v1/responses/responses
Cause :     un endpoint complet a été saisi comme Base URL

Incorrect : Base URL Claude Code = https://www.bettertoken.ai/v1/messages
Cause :     Claude Code ajoutera /v1/messages une seconde fois

Incorrect : un client OpenAI-compatible utilise https://bettertoken.ai
Cause :     le chemin /v1 requis par cette entrée manque

Corrigez ces assemblages avant de changer la clé, le modèle ou les paramètres avancés.

Ce qu’il ne faut pas faire

• Ne changez pas Base URL, API Key et Model ID en même temps.
• Ne copiez pas la même Base URL dans tous les outils.
• Ne déduisez pas le protocole du nom du modèle.
• Ne reprenez pas une adresse d’une ancienne capture ou d’un ancien guide sans vérifier la documentation actuelle.
• N’utilisez pas un vrai projet avec droits d’écriture pour le premier test.
• Ne publiez pas l’API Key complète dans une issue, un chat ou une capture.
• Ne réglez pas streaming, tools, MCP ou timeout avant qu’une requête simple fonctionne.

Questions fréquentes

Qu’est-ce qu’une Base URL ?

C’est l’adresse racine d’un serveur ou d’une passerelle API. Le client ajoute un endpoint comme /responses, /chat/completions ou /v1/messages.

Quelle différence entre Base URL et endpoint ?

La Base URL est la racine commune de plusieurs requêtes. L’endpoint est le chemin d’une ressource ou d’une opération précise. Ensemble, ils forment l’URL complète.

Pourquoi une mauvaise Base URL renvoie-t-elle souvent 404 ?

Les causes habituelles sont un /v1 ou un endpoint dupliqué, un chemin de base manquant, ou une incompatibilité entre client OpenAI-compatible et adresse Anthropic-compatible, ou inversement.

Toutes les Base URL BetterToken exigent-elles /v1 ?

Non. Codex, Cursor, Cline et les autres clients OpenAI-compatible utilisent généralement https://www.bettertoken.ai/v1. Claude Code utilise https://bettertoken.ai et ajoute /v1/messages.

Pourquoi ma modification de Base URL n’est-elle pas prise en compte ?

Le processus peut conserver d’anciennes variables d’environnement ou une configuration en cache. Fermez complètement le client et les processus en arrière-plan, puis ouvrez un nouveau terminal ou relancez l’application.

Base URL et MCP sont-ils identiques ?

Non. Base URL et API Key règlent le routage et l’authentification des requêtes vers les modèles. MCP connecte des outils externes, fichiers, bases de données et autres contextes. Consultez MCP, API Key et Base URL.

Étape suivante

Ouvrez la documentation BetterToken, sélectionnez l’outil réellement utilisé et copiez uniquement la Base URL actuelle indiquée sur sa page. Envoyez une requête courte avec votre API Key, sans streaming ni tools, puis contrôlez dans le Dashboard l’heure, le statut, le modèle et la consommation de tokens.

Une fois la requête de base réussie, réactivez le changement de modèle, le contexte long, tools, MCP et streaming un par un. Vous séparerez ainsi « l’adresse est-elle correcte ? » de « la fonction avancée marche-t-elle ? » et trouverez la cause beaucoup plus vite.