Qué es una Base URL: estructura de una API y solución de errores 401/404

Si ya has creado una API Key pero el cliente devuelve 401, 404, 405, model not found, abre una página de inicio de sesión o entrega HTML en lugar de JSON, no cambies a la vez la clave, el modelo y la dirección. Primero aclara qué es la Base URL y después revisa la configuración en este orden: protocolo → dirección raíz → versión de la API → endpoint → autenticación → modelo.

La Base URL es la dirección raíz de un servidor o gateway de API. Una biblioteca cliente, un SDK o una herramienta de línea de comandos añade la ruta de un recurso concreto —el endpoint— para formar la URL completa de la solicitud.

Los ejemplos utilizan BetterToken, pero el método también sirve para otros gateways, proxies propios y servicios compatibles con los protocolos de OpenAI o Anthropic.

¿Qué es una Base URL en una API?

La fórmula más sencilla es:

URL completa de la solicitud = Base URL + ruta del endpoint

Ejemplo de una solicitud compatible con OpenAI:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /responses
URL completa: https://www.bettertoken.ai/v1/responses

Otro endpoint habitual es /chat/completions:

Base URL:  https://www.bettertoken.ai/v1
Endpoint:  /chat/completions
URL completa: https://www.bettertoken.ai/v1/chat/completions

En una aplicación real, el cliente suele normalizar la barra entre ambos fragmentos. La cuestión importante no es cómo concatenar las cadenas a mano, sino si el campo Base URL ya incluye una ruta que el cliente volverá a añadir.

Partes de una URL de API

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

Parte	Ejemplo	Función
Esquema	https://	Define cómo se establece la conexión
Host	bettertoken.ai	Identifica el servicio de API
Ruta base	/v1	Selecciona una versión o entrada común
Endpoint	/responses	Selecciona un recurso u operación

En algunos servicios la Base URL contiene solo el esquema y el dominio; en otros también incluye una ruta como /v1. No existe un sufijo universal. Usa siempre la documentación vigente del servicio y del cliente.

Lo que no es una Base URL

Concepto que suele confundirse	Diferencia
Página principal del sitio	Puede devolver HTML; una Base URL de API está pensada para solicitudes programáticas
URL completa	Ya contiene un endpoint como /responses, /chat/completions o /v1/messages
API Key	La clave autentica; la Base URL decide adónde se envía la solicitud
Model ID	Selecciona el modelo, pero no el protocolo ni la ruta
Dirección de un servidor MCP	MCP conecta herramientas y datos; no sustituye la Base URL de la API del modelo

Que una dirección se abra en el navegador no demuestra que sea la Base URL correcta. Muchos puntos raíz de API no muestran una página legible. A la inversa, una página de inicio de sesión puede pertenecer al sitio web y no a la API.

Elige la dirección por el protocolo del cliente, no por el nombre del modelo

Un mismo gateway puede ofrecer entradas compatibles con OpenAI y con Anthropic. El protocolo que espera el cliente importa más que si el modelo se llama GPT, Claude, Kimi o GLM.

La documentación actual de BetterToken usa estas reglas:

Cliente o caso	Protocolo habitual	Base URL que debes introducir	Ruta que añade el cliente
Codex	OpenAI Responses	https://www.bettertoken.ai/v1	/responses
Cursor, Cline, OpenCode y similares	OpenAI-compatible	https://www.bettertoken.ai/v1	La que corresponda, como /chat/completions
Claude Code	Anthropic-compatible	https://bettertoken.ai	/v1/messages
Solicitud HTTP escrita por ti	Depende del formato	La dirección del protocolo elegido	El endpoint se indica en el código

Consulta API compatible con OpenAI frente a API compatible con Anthropic. No configures todos los programas con la dirección de Anthropic solo porque quieras usar un modelo Claude, ni ignores el protocolo del cliente porque el modelo sea GPT.

Cinco comprobaciones de la Base URL

Modifica una sola variable cada vez y repite la misma solicitud corta después de cada cambio. Así sabrás qué capa causaba el fallo.

1. Confirma el protocolo que espera el cliente

Revisa el provider o el tipo de API dentro de la herramienta:

• Codex utiliza OpenAI Responses.
• Cursor, Cline, OpenCode y muchas herramientas similares suelen utilizar un provider OpenAI-compatible.
• Claude Code utiliza el protocolo Messages compatible con Anthropic.
• En un script propio, el formato implementado en el código determina el protocolo.

Cambiar de modelo no corrige una incompatibilidad de protocolo. Los campos, la autenticación y las rutas pueden ser diferentes.

2. Introduce solo la dirección raíz, no un endpoint completo

Un campo llamado base_url, Base URL, API base o endpoint base suele esperar la raíz compartida.

Correcto:

https://www.bettertoken.ai/v1

Errores frecuentes:

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

Si el cliente añade /responses, el primer error puede terminar así:

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

En Claude Code tampoco debes poner https://www.bettertoken.ai/v1/messages en ANTHROPIC_BASE_URL; el propio programa añade /v1/messages.

3. Asegúrate de que /v1 aparezca una sola vez

La Base URL de BetterToken para clientes OpenAI-compatible ya contiene /v1. Si el SDK ofrece además api_version, path_prefix o un campo parecido, no añadas otro /v1 salvo que su documentación lo exija.

Esta URL en los logs casi siempre indica un error de unión:

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

En el extremo contrario, una solicitud OpenAI-compatible sin /v1 puede devolver 404, HTML del sitio o una redirección al inicio de sesión.

4. Prueba el endpoint con la solicitud más pequeña posible

Desactiva streaming, tools, MCP y contexto largo. Envía una frase breve desde el mismo cliente. No empieces con una tarea que pueda escribir en un repositorio real.

Inicia Codex:

codex

Después escribe:

Responde con una sola frase breve: la conexión funciona.

Inicia Claude Code:

claude

Después escribe:

Responde con una sola frase breve: la conexión funciona.

En una solicitud HTTP directa, usa un Model ID disponible actualmente en Setup o Model Plaza. La guía vigente de Codex usa gpt-6-astra como ejemplo, pero la disponibilidad real para tu clave debe verificarse en el panel. Activa streaming, tools o tareas largas solo después de que funcione la prueba mínima.

5. Reinicia el cliente por completo

Muchas CLI, aplicaciones de escritorio y extensiones leen las variables de entorno y los archivos de configuración solo al iniciarse. Guardar el archivo no implica que el proceso en ejecución haya cargado el nuevo valor.

Después de un cambio:

1. Cierra la CLI, la aplicación o la ventana del editor.
2. Comprueba que los procesos relacionados hayan terminado.
3. Abre un terminal nuevo o reinicia la aplicación.
4. Repite la misma solicitud corta.

De lo contrario, puedes estar viendo el archivo nuevo mientras sigues probando la Base URL antigua.

Cómo interpretar los errores habituales

Síntoma	Qué comprobar primero	Siguiente paso
404 Not Found	/v1 duplicado, endpoint repetido o protocolo incorrecto	Compara la URL real de los logs con la documentación
HTML o página de acceso	Ruta web en lugar de ruta de API	Revisa host, /v1 y endpoint
401	API Key, variable de autenticación y configuración activa	Elimina espacios accidentales y reinicia el cliente
403	Acceso de la clave al modelo o la ruta	Comprueba la disponibilidad en Setup o el panel
405 Method Not Allowed	Método HTTP y endpoint	Confirma si la ruta requiere POST u otro método
model not found	Base URL y protocolo antes que Model ID	No ocultes un error de ruta cambiando primero de modelo
Timeout o stream interrumpido	Solicitud corta sin streaming	Si funciona, revisa streaming y timeout por separado
No cambia tras editar	Ruta del archivo, variables que sobrescriben, procesos	Cierra todo y reinicia

Un 401 no demuestra que la URL sea correcta, y un 404 no demuestra que falte el modelo. El código solo describe cómo respondió el servidor a la solicitud recibida.

Comprobación rápida para Codex y Claude Code

Codex

La parte de la configuración de Codex relacionada con la dirección debe parecerse a esta:

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

La API Key se guarda en auth.json, dentro del mismo directorio de configuración. Consulta la guía completa de Codex para los demás campos. Codex añade /responses, así que no lo incluyas en base_url.

Claude Code

Las variables de dirección y autenticación son:

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

Este fragmento solo destaca la dirección y el token. Usa la configuración completa de la guía de Claude Code. No añadas /v1 ni /messages a ANTHROPIC_BASE_URL.

Cuatro fallos típicos al unir rutas

Incorrecto: https://www.bettertoken.ai/v1/v1/responses
Causa:      la Base URL y el cliente añadieron /v1

Incorrecto: https://www.bettertoken.ai/v1/responses/responses
Causa:      se introdujo un endpoint completo como Base URL

Incorrecto: Base URL de Claude Code = https://www.bettertoken.ai/v1/messages
Causa:      Claude Code volverá a añadir /v1/messages

Incorrecto: un cliente OpenAI-compatible usa https://bettertoken.ai
Causa:      falta la ruta /v1 exigida por esa entrada

Corrige primero estas uniones y después revisa la clave, el modelo o los parámetros avanzados.

Qué no debes hacer

• No cambies a la vez Base URL, API Key y Model ID.
• No copies la misma Base URL en todas las herramientas.
• No deduzcas el protocolo por el nombre del modelo.
• No reutilices una dirección de una captura o guía antigua sin comprobar la documentación actual.
• No uses un proyecto real con permisos de escritura para la primera prueba.
• No publiques la API Key completa en incidencias, chats o capturas.
• No ajustes streaming, tools, MCP o timeouts antes de que funcione una solicitud básica.

Preguntas frecuentes

¿Qué es una Base URL?

Es la dirección raíz de un servidor o gateway de API. El cliente le añade un endpoint como /responses, /chat/completions o /v1/messages.

¿Qué diferencia hay entre Base URL y endpoint?

La Base URL es la raíz común de muchas solicitudes. El endpoint es la ruta de un recurso u operación concretos. Juntos forman la URL completa.

¿Por qué una Base URL incorrecta suele devolver 404?

Normalmente por un /v1 duplicado, un endpoint repetido, una ruta base ausente o una incompatibilidad entre un cliente OpenAI-compatible y una dirección Anthropic-compatible, o al revés.

¿Todas las Base URL de BetterToken necesitan /v1?

No. Codex, Cursor, Cline y otros clientes OpenAI-compatible suelen usar https://www.bettertoken.ai/v1. Claude Code usa https://bettertoken.ai y añade /v1/messages.

¿Por qué el cambio de Base URL no se aplicó?

El proceso puede seguir usando variables o configuración antiguas. Cierra por completo el cliente y sus procesos en segundo plano, abre un terminal nuevo o reinicia la aplicación.

¿Base URL y MCP son lo mismo?

No. Base URL y API Key configuran el enrutamiento y la autenticación de las solicitudes a modelos. MCP conecta herramientas externas, archivos, bases de datos y contexto. Consulta MCP frente a API Key y Base URL.

Siguiente paso

Abre la documentación de BetterToken, selecciona la herramienta que utilizas y copia únicamente la Base URL vigente que aparece en esa página. Envía una solicitud corta con tu API Key, sin streaming ni tools, y revisa en el Dashboard la hora, el estado, el modelo y el consumo de tokens.

Cuando funcione la solicitud básica, vuelve a activar el cambio de modelo, el contexto largo, tools, MCP y streaming de uno en uno. Así separarás “¿es correcta la dirección?” de “¿funciona la característica avanzada?” y localizarás el problema mucho más rápido.