Error de Base URL: comprueba protocolo, ruta y endpoint
Un orden práctico para comprobar una Base URL: protocolo, dominio, versión de API, endpoint y configuración del cliente, con una prueba corta tras cada cambio.
Si ya has creado la API Key pero el cliente devuelve 401, 404, 405, model not found o simplemente abre una página de inicio de sesión, no cambies la clave, el modelo y la dirección al mismo tiempo. Primero identifica qué contrato espera el cliente: compatible con OpenAI o compatible con Anthropic. Después revisa la dirección por capas: https → dominio → ruta base → endpoint. Tras cada cambio, envía una única solicitud corta. Así podrás ver en qué capa deja de coincidir la configuración.
Con BetterToken esta distinción es importante: los clientes compatibles con OpenAI usan https://www.bettertoken.ai/v1%60?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol como Base URL. Claude Code usa la Base URL compatible con Anthropic https://bettertoken.ai` y añade por sí mismo la ruta necesaria. No son dos variantes intercambiables de la misma cadena. Confirma siempre los valores y límites actuales de tu herramienta en la documentación de BetterToken.
Separa la Base URL de la URL completa de la solicitud
La Base URL es la dirección que introduces en el campo del proveedor o en el archivo de configuración del cliente. La URL completa de la solicitud se forma cuando la biblioteca o la CLI añade la ruta del recurso.
Si escribes tú mismo una solicitud Anthropic Messages sin SDK, la ruta completa es https://www.bettertoken.ai/v1/messages%60.?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol Sin embargo, ese no es el valor del campo Base URL de Claude Code. En un cliente compatible con OpenAI, la Base URL suele terminar en /v1` y el cliente añade el endpoint concreto. Este principio está confirmado en las guías de Claude Code y Codex, verificadas el 15 de agosto de 2026.
Cinco comprobaciones en el orden correcto
Haz las comprobaciones de forma secuencial. Repite la misma solicitud corta después de cada punto para no mezclar varias causas en un solo resultado.
- Determina qué protocolo espera el cliente.
- Introduce únicamente la Base URL adecuada, sin endpoint.
- Comprueba que
/v1aparece exactamente una vez en la URL de la solicitud. - Ejecuta una solicitud mínima sin streaming ni herramientas.
- Reinicia completamente el cliente y repite la prueba.
1. Comprueba el protocolo, no el nombre del modelo
Mira el tipo de integración dentro de la herramienta. Codex, Cursor, Cline, OpenCode y muchos otros clientes usan una configuración compatible con OpenAI. Claude Code usa el contrato compatible con Anthropic. Si un cliente espera un formato y recibe el otro, cambiar de modelo no arreglará el problema: el servidor y el cliente necesitan campos y rutas diferentes.
No lo deduzcas por el nombre del modelo. Abre la página de Docs de tu herramienta concreta y busca la sección sobre provider, API Key y Base URL.
2. Comprueba la dirección base sin ruta adicional
Para la configuración compatible con OpenAI, usa la dirección indicada en la documentación de la herramienta:
Para Claude Code, usa la dirección base sin /v1 ni /messages:
Un fallo frecuente consiste en copiar la URL completa de un ejemplo de curl en un campo gráfico de Base URL. El cliente añade entonces su endpoint y se crea una ruta que no existe. Si el campo se llama base_url, endpoint base o API base, normalmente no debes introducir ahí el nombre de un recurso.
3. Comprueba quién gestiona la versión /v1
En la configuración BetterToken compatible con OpenAI, la versión de API ya forma parte de la Base URL. Si tu SDK permite definir un prefijo de versión por separado, no añadas un segundo /v1 sin una indicación explícita en la documentación del SDK.
Es fácil detectarlo en los logs: .../v1/v1/... casi siempre significa que las rutas se han concatenado mal. Por el contrario, la ausencia de /v1 en una solicitud compatible con OpenAI puede causar 404 o una respuesta HTML en lugar de JSON.
4. Comprueba el endpoint con una solicitud mínima
Antes de activar streaming, herramientas o contexto largo, envía una sola solicitud corta a través del mismo cliente. Para una solicitud OpenAI-compatible sin SDK, el endpoint es el recurso que sigue a la Base URL; para Anthropic Messages es /v1/messages.
La prueba debe ser pequeña y segura: un prompt corto, el Model ID actual de Setup o Model Plaza y tu propia API Key. No incluyas la clave en incidencias, capturas de pantalla ni comandos que vayas a compartir. Si la solicitud devuelve JSON con estado de éxito, modelo y uso, la capa de dirección está resuelta. Solo entonces tiene sentido revisar límites, modelo o parámetros de la tarea.
5. Reinicia completamente el cliente después de cada cambio
Muchas CLI y aplicaciones de escritorio solo leen variables y configuración al iniciarse. Guardar el archivo no basta: cierra el proceso, abre una nueva terminal o reinicia la aplicación, y después repite la misma prueba corta. De otro modo seguirás probando la Base URL anterior aunque el editor ya muestre la nueva.
Cómo interpretar las respuestas habituales
Un 401 no siempre significa que la dirección sea errónea, y un 404 no siempre significa que falte un modelo. Por eso importa el orden: primero URL, después autenticación, después modelo y por último las funciones avanzadas.
Flujo rápido para Codex y Claude Code
Si configuras Codex, usa un proveedor compatible con OpenAI y sigue la guía actual de Codex: Base URL `https://www.bettertoken.ai/v1%60,?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-022&utm_content=base-url-oshibka-kak-proverit-put-i-protokol tu propia API Key de BetterToken y un Model ID actual. Reinicia Codex y ejecuta una pequeña tarea de solo lectura en un directorio de prueba. En el Dashboard puedes comprobar hora, estado, modelo y consumo de tokens; muestra esos campos, pero no promete conservar el texto completo del prompt ni de la respuesta.
Si configuras Claude Code, sigue la guía de Claude Code: Base URL compatible con Anthropic https://bettertoken.ai, tu propia clave y el modelo indicado en la guía actual. No copies el /v1 de OpenAI ni añadas /messages a este campo. Después de reiniciar, ejecuta una solicitud pequeña antes de conectar herramientas o MCP.
Qué no conviene hacer
- No cambies Base URL, API Key y Model ID a la vez: perderás la causa del error.
- No uses la misma dirección para todas las herramientas: el protocolo lo define el cliente, no tu patrón de URL habitual.
- No copies una ruta de una guía antigua sin comprobar la fecha y la página de la herramienta.
- No pruebes la configuración en un repositorio real de trabajo con acceso de escritura. Para la primera solicitud, usa un directorio de prueba vacío y una tarea de solo lectura.
- No envíes la clave completa al soporte. Bastan el estado, la hora, el nombre de la herramienta y una URL de solicitud depurada.
Siguiente paso
Abre la documentación de BetterToken para tu herramienta, crea tu propia API Key en tu cuenta BetterToken, copia solo la Base URL actual del protocolo elegido y ejecuta una prueba corta. Si funciona, compara en el Dashboard el estado, el modelo y el consumo de tokens. Es más fiable que limitarse a comprobar que un formulario de configuración se ha guardado.