O que é Base URL: estrutura de API e correção de erros 401/404

Se a API Key já foi criada, mas o cliente retorna 401, 404, 405, model not found, abre uma página de login ou recebe HTML em vez de JSON, não altere a chave, o modelo e o endereço ao mesmo tempo. Primeiro entenda o que é Base URL e depois verifique a configuração nesta ordem: protocolo → endereço raiz → versão da API → endpoint → autenticação → modelo.

Base URL é o endereço raiz de um servidor ou gateway de API. Uma biblioteca cliente, um SDK ou uma ferramenta de linha de comando acrescenta o caminho de um recurso específico — o endpoint — para formar a URL completa da requisição.

Os exemplos usam a BetterToken, mas o mesmo método vale para outros gateways, proxies próprios e serviços compatíveis com os protocolos da OpenAI ou da Anthropic.

O que é Base URL em uma API?

A fórmula mais simples é:

URL completa da requisição = Base URL + caminho do endpoint

Exemplo de uma requisição compatível com OpenAI:

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

Outro endpoint comum é /chat/completions:

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

Em uma aplicação real, o cliente costuma normalizar a barra entre as duas partes. A pergunta importante não é como concatenar strings manualmente, e sim se o campo Base URL já contém um caminho que o cliente acrescentará outra vez.

Partes de uma URL de API

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

Parte	Exemplo	Função
Esquema	https://	Define como a conexão será estabelecida
Host	bettertoken.ai	Identifica o serviço de API
Caminho base	/v1	Seleciona uma versão ou entrada comum
Endpoint	/responses	Seleciona um recurso ou uma operação

Em alguns serviços, a Base URL contém apenas esquema e domínio. Em outros, ela também inclui um caminho como /v1. Não existe um sufixo universal: use a documentação atual do serviço e do cliente.

O que não é uma Base URL

Conceito confundido com frequência	Diferença
Página inicial do site	Pode retornar HTML; a Base URL da API é destinada a requisições programáticas
URL completa	Já contém um endpoint como /responses, /chat/completions ou /v1/messages
API Key	A chave autentica; a Base URL determina para onde a requisição vai
Model ID	Seleciona o modelo, mas não o protocolo nem a rota
Endereço de servidor MCP	O MCP conecta ferramentas e dados; não substitui a Base URL da API do modelo

O fato de um endereço abrir no navegador não prova que ele seja a Base URL correta. Muitas raízes de API válidas não exibem uma página legível. Por outro lado, uma página de login pode pertencer ao site, não à API.

Escolha o endereço pelo protocolo do cliente, não pelo nome do modelo

Um mesmo gateway pode oferecer entradas compatíveis com OpenAI e com Anthropic. O protocolo esperado pelo cliente é mais importante do que o modelo se chamar GPT, Claude, Kimi ou GLM.

A documentação atual da BetterToken segue estas regras:

Cliente ou cenário	Protocolo típico	Base URL a informar	Caminho acrescentado pelo cliente
Codex	OpenAI Responses	https://www.bettertoken.ai/v1	/responses
Cursor, Cline, OpenCode e semelhantes	OpenAI-compatible	https://www.bettertoken.ai/v1	O endpoint necessário, como /chat/completions
Claude Code	Anthropic-compatible	https://bettertoken.ai	/v1/messages
Requisição HTTP escrita por você	Depende do formato	O endereço do protocolo escolhido	O endpoint é informado no código

Consulte API compatível com OpenAI versus API compatível com Anthropic. Não use o endereço Anthropic em todas as ferramentas só porque pretende chamar um modelo Claude, nem ignore o protocolo do cliente porque o modelo é GPT.

Cinco verificações da Base URL

Altere apenas uma variável por vez e repita a mesma requisição curta após cada mudança. Assim fica claro em qual camada estava o problema.

1. Confirme o protocolo esperado pelo cliente

Verifique o provider ou o tipo de API dentro da ferramenta:

• O Codex usa OpenAI Responses.
• Cursor, Cline, OpenCode e muitas ferramentas parecidas normalmente usam um provider OpenAI-compatible.
• O Claude Code usa o protocolo Messages compatível com Anthropic.
• Em um script próprio, o formato implementado no código define o protocolo.

Trocar o modelo não corrige incompatibilidade de protocolo. Campos, autenticação e caminhos de endpoint podem ser diferentes.

2. Informe apenas o endereço raiz, não um endpoint completo

Um campo chamado base_url, Base URL, API base ou endpoint base normalmente espera a raiz compartilhada.

Correto:

https://www.bettertoken.ai/v1

Erros comuns:

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

Se o cliente acrescentar /responses, o primeiro erro pode resultar em:

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

No Claude Code, também não coloque https://www.bettertoken.ai/v1/messages em ANTHROPIC_BASE_URL; o programa acrescenta /v1/messages sozinho.

3. Garanta que /v1 apareça uma única vez

A Base URL da BetterToken para clientes OpenAI-compatible já contém /v1. Se o SDK também tiver api_version, path_prefix ou um campo parecido, não adicione outro /v1 a menos que a documentação exija isso.

Esta URL nos logs quase sempre aponta para uma montagem incorreta:

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

No caso oposto, uma requisição OpenAI-compatible sem /v1 pode retornar 404, HTML do site ou redirecionamento para login.

4. Teste o endpoint com a menor requisição possível

Desative streaming, tools, MCP e contexto longo. Envie uma frase curta pelo mesmo cliente. Não comece com uma tarefa que possa escrever em um repositório real.

Inicie o Codex:

codex

Depois digite:

Responda com apenas uma frase curta: a conexão está funcionando.

Inicie o Claude Code:

claude

Depois digite:

Responda com apenas uma frase curta: a conexão está funcionando.

Em uma requisição HTTP direta, use um Model ID disponível atualmente no Setup ou no Model Plaza. O guia atual do Codex usa gpt-6-astra como exemplo, mas a disponibilidade para sua chave deve ser confirmada no painel. Só reative streaming, tools ou tarefas longas depois que a requisição mínima funcionar.

5. Reinicie o cliente por completo

Muitas CLIs, aplicações desktop e extensões de editor leem variáveis de ambiente e arquivos de configuração apenas ao iniciar. Salvar o arquivo não significa que o processo em execução carregou o novo valor.

Depois de uma alteração:

1. Feche a CLI, o aplicativo ou a janela do editor.
2. Confirme que os processos relacionados foram encerrados.
3. Abra um novo terminal ou reinicie o aplicativo.
4. Repita a mesma requisição curta.

Caso contrário, você pode estar vendo o arquivo novo enquanto ainda testa a Base URL antiga.

Como interpretar erros comuns

Sintoma	O que verificar primeiro	Próxima ação
404 Not Found	/v1 duplicado, endpoint repetido ou protocolo incorreto	Compare a URL real dos logs com a documentação
HTML ou página de login	Rota web em vez de rota de API	Revise host, /v1 e endpoint
401	API Key, variável de autenticação e configuração ativa	Remova espaços acidentais e reinicie o cliente
403	Acesso da chave ao modelo ou à rota	Verifique a disponibilidade no Setup ou painel
405 Method Not Allowed	Método HTTP e endpoint	Confirme se a rota requer POST ou outro método
model not found	Base URL e protocolo antes do Model ID	Não esconda um erro de rota trocando primeiro o modelo
Timeout ou stream interrompido	Requisição curta sem streaming	Se funcionar, revise streaming e timeout separadamente
Nada muda após editar	Caminho do arquivo, variáveis sobrescrevendo, processo	Encerre tudo e reinicie

Um 401 não prova que a URL está correta, e um 404 não prova que o modelo não existe. O status só descreve como o servidor tratou a requisição recebida.

Verificação rápida para Codex e Claude Code

Codex

A parte da configuração do Codex relacionada ao endereço deve se parecer com isto:

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

A API Key fica em auth.json, no mesmo diretório de configuração. Consulte o guia completo do Codex para os demais campos e regras de autenticação. O Codex acrescenta /responses; não o inclua em base_url.

Claude Code

As variáveis principais são:

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

Este trecho destaca apenas endereço e autenticação. Use a configuração completa do guia do Claude Code. Não acrescente /v1 nem /messages a ANTHROPIC_BASE_URL.

Quatro falhas comuns ao montar a URL

Errado: https://www.bettertoken.ai/v1/v1/responses
Causa:  a Base URL e o cliente acrescentaram /v1

Errado: https://www.bettertoken.ai/v1/responses/responses
Causa:  um endpoint completo foi informado como Base URL

Errado: Base URL do Claude Code = https://www.bettertoken.ai/v1/messages
Causa:  o Claude Code acrescentará /v1/messages novamente

Errado: um cliente OpenAI-compatible usa https://bettertoken.ai
Causa:  falta o caminho /v1 exigido por essa entrada

Corrija essas montagens antes de trocar chave, modelo ou parâmetros avançados.

O que não fazer

• Não altere Base URL, API Key e Model ID ao mesmo tempo.
• Não copie a mesma Base URL para todas as ferramentas.
• Não deduza o protocolo pelo nome do modelo.
• Não copie endereço de captura ou guia antigo sem conferir a documentação atual.
• Não use um projeto real com permissão de escrita no primeiro teste.
• Não publique a API Key completa em issue, chat ou captura de tela.
• Não ajuste streaming, tools, MCP ou timeout antes que uma requisição básica funcione.

Perguntas frequentes

O que é Base URL?

É o endereço raiz de um servidor ou gateway de API. O cliente acrescenta um endpoint como /responses, /chat/completions ou /v1/messages.

Qual é a diferença entre Base URL e endpoint?

A Base URL é a raiz comum de várias requisições. O endpoint é o caminho de um recurso ou operação específicos. Juntos formam a URL completa.

Por que uma Base URL incorreta costuma retornar 404?

Geralmente por /v1 duplicado, endpoint repetido, caminho base ausente ou incompatibilidade entre um cliente OpenAI-compatible e um endereço Anthropic-compatible, ou vice-versa.

Toda Base URL da BetterToken precisa de /v1?

Não. Codex, Cursor, Cline e outros clientes OpenAI-compatible normalmente usam https://www.bettertoken.ai/v1. O Claude Code usa https://bettertoken.ai e acrescenta /v1/messages.

Por que a alteração da Base URL não foi aplicada?

O processo pode continuar com variáveis de ambiente ou configuração antigas. Encerre totalmente o cliente e processos em segundo plano, abra um terminal novo ou reinicie o aplicativo.

Base URL e MCP são a mesma coisa?

Não. Base URL e API Key configuram roteamento e autenticação das requisições ao modelo. MCP conecta ferramentas externas, arquivos, bancos de dados e outros contextos. Leia MCP versus API Key e Base URL.

Próximo passo

Abra a documentação da BetterToken, selecione a ferramenta que você realmente usa e copie somente a Base URL atual mostrada nessa página. Envie uma requisição curta com sua API Key, sem streaming e tools, e confira no Dashboard horário, status, modelo e consumo de tokens.

Depois que a requisição básica funcionar, reative troca de modelo, contexto longo, tools, MCP e streaming uma camada por vez. Assim você separa “o endereço está correto?” de “o recurso avançado funciona?” e encontra o problema muito mais rápido.