Erro de Base URL: verifique protocolo, caminho e endpoint
Uma sequência prática para verificar a Base URL: protocolo, domínio, versão da API, endpoint e configuração do cliente, testando cada alteração.
Se a API Key já foi criada, mas o cliente retorna 401, 404, 405, model not found ou abre uma página de login, não altere a chave, o modelo e o endereço ao mesmo tempo. Primeiro descubra qual contrato o cliente espera — OpenAI-compatible ou Anthropic-compatible — e depois confira o endereço por camadas: https → domínio → caminho base → endpoint. Envie uma requisição curta após cada alteração. Assim fica claro em qual camada a configuração deixou de corresponder.
No BetterToken, clientes OpenAI-compatible usam a 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 O Claude Code usa a Base URL Anthropic-compatible https://bettertoken.ai` e adiciona o caminho necessário por conta própria. Não são versões intercambiáveis da mesma string. Confirme sempre os valores atuais e as limitações do seu instrumento na documentação do BetterToken.
Diferencie Base URL de URL completa da requisição
A Base URL é o endereço inserido no campo de provider ou no arquivo de configuração do cliente. A URL completa da requisição é formada quando a biblioteca ou CLI adiciona o caminho do recurso.
Se você escreve uma requisição Anthropic Messages diretamente, o caminho completo é 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 Esse não é o valor do campo Base URL do Claude Code. Em um cliente OpenAI-compatible, o endereço base normalmente termina em /v1`, e o próprio cliente adiciona o endpoint específico. A diferença está documentada nos guias de Claude Code e Codex, verificados em 15 de agosto de 2026.
Faça cinco verificações nesta ordem
Execute as verificações em sequência. Após cada uma, repita a mesma requisição pequena para não misturar várias causas em um único resultado.
- Identifique o protocolo esperado pelo cliente.
- Informe apenas a Base URL correspondente, sem endpoint.
- Confirme que
/v1aparece exatamente uma vez na URL da requisição. - Execute uma requisição mínima, sem streaming ou tools.
- Reinicie completamente o cliente e repita o teste.
1. Verifique o protocolo, não o nome do modelo
Veja o tipo de integração no próprio instrumento. Codex, Cursor, Cline, OpenCode e muitos outros clientes usam uma configuração OpenAI-compatible. Claude Code usa um contrato Anthropic-compatible. Se o cliente espera um formato e recebe outro, trocar o modelo não resolverá: servidor e cliente precisam de campos e caminhos diferentes.
Não deduza o protocolo pelo nome do modelo. Abra a página de Docs do seu instrumento específico e localize as seções de provider, API Key e Base URL.
2. Compare o endereço base sem caminho extra
Para uma configuração OpenAI-compatible, use o endereço indicado na documentação do instrumento:
Para Claude Code, use o endereço base sem /v1 nem /messages:
Uma falha comum acontece quando a URL completa de um exemplo curl é colada no campo Base URL da interface. O cliente adiciona seu próprio endpoint e forma uma rota inexistente. Se o campo se chama base_url, endpoint base ou API base, ele normalmente não deve conter o nome de um recurso.
3. Verifique quem controla o prefixo de versão /v1
A versão da API deve aparecer exatamente uma vez. Na configuração OpenAI-compatible do BetterToken, ela já está incluída na Base URL. Se o seu SDK permite definir um prefixo de versão separadamente, não adicione um segundo /v1, a menos que a documentação do SDK o exija explicitamente.
Nos logs, isso costuma ser fácil de identificar: .../v1/v1/... quase sempre significa que a URL foi concatenada incorretamente. Por outro lado, remover /v1 de uma requisição OpenAI-compatible pode resultar em 404 ou HTML no lugar de JSON.
4. Teste o endpoint com uma requisição mínima
Antes de ativar streaming, tools ou contexto longo, faça uma requisição curta pelo mesmo cliente. Em uma requisição OpenAI-compatible direta, o endpoint é o recurso depois da Base URL; em Anthropic Messages, é /v1/messages.
Mantenha o teste pequeno e seguro: use um prompt curto, o Model ID atual do painel Setup ou model plaza e a sua própria API Key. Não coloque a chave em issue, captura de tela ou comando que pretende compartilhar. Se a resposta retornar JSON com status de sucesso, modelo e usage, a camada de endereço está funcionando; só então investigue limites, seleção de modelo ou parâmetros da tarefa.
5. Reinicie o cliente depois de mudar a configuração
Muitas CLIs e aplicações desktop leem variáveis de ambiente e configuração apenas na inicialização. Salvar o arquivo não basta: pare o processo, abra um terminal novo ou reinicie o aplicativo e repita o mesmo teste pequeno. Caso contrário, você pode estar testando a Base URL antiga enquanto vê a nova no editor.
Como interpretar respostas comuns
Um 401 nem sempre significa que o endereço está incorreto, e um 404 nem sempre quer dizer que o modelo não existe. Por isso a ordem importa: URL primeiro, autenticação depois, modelo em seguida e recursos avançados por último.
Caminhos rápidos para Codex e Claude Code
Para Codex, use um provider OpenAI-compatible e siga o guia atual 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 sua API Key BetterToken e um Model ID atual. Reinicie o Codex e faça uma pequena requisição somente de leitura em um diretório de teste. No Dashboard, confira horário, status, modelo e consumo de tokens; o Dashboard mostra esses campos, mas não promete guardar todo o texto do prompt ou da resposta.
Para Claude Code, siga o guia de Claude Code: use a Base URL Anthropic-compatible https://bettertoken.ai, sua própria API Key e o modelo indicado no guia atual. Não leve o caminho OpenAI /v1 para esse campo nem adicione /messages manualmente. Depois de reiniciar, faça uma requisição pequena antes de ativar tools ou MCP.
Evite estas armadilhas de depuração
- Não altere Base URL, API Key e Model ID de uma vez; você perderá a causa do erro.
- Não use um único endereço para todos os instrumentos: o protocolo do cliente, não um padrão de URL conhecido, define a configuração.
- Não copie um caminho de um guia antigo sem verificar a data e a página do seu instrumento.
- Não teste a primeira mudança de configuração em um repositório de produção com permissão de escrita. Use um diretório de teste vazio e uma tarefa somente de leitura.
- Não envie uma chave completa ao suporte. Um status, horário, nome do instrumento e URL de requisição com dados sensíveis removidos bastam para iniciar a análise.
Próximo passo
Abra os Docs do BetterToken para seu instrumento, crie sua própria API Key BetterToken, copie apenas a Base URL atual para o protocolo escolhido e faça um teste curto. Quando ele funcionar, use o Dashboard para confirmar status, modelo e consumo de tokens — isso é mais confiável do que considerar um formulário salvo como prova de que o cliente está usando o endereço novo.