Erro 401 ou 404 da API: chave, base URL ou id do modelo errados

Sua requisição falhou com um código de status e você não sabe o que verificar primeiro. Resposta curta: 401 geralmente aponta para a chave, 404 geralmente significa que você está batendo no lugar errado — seja o endereço (base URL e caminho) ou o id do modelo. Três coisas para verificar, nesta ordem, e um comando curl que comprova a correção.

A página de códigos de erro da OpenAI (verificada em 26 de outubro de 2026) lista duas mensagens de 401: "Invalid Authentication" e "Incorrect API key provided". A correção indicada é a mesma para ambas: verifique a chave ou gere uma nova. A página não documenta nenhum 404 para a própria API, então para 404 a regra abaixo vem de como endpoints compatíveis com OpenAI funcionam, não daquela página.

A forma rápida de diferenciá-los#

O texto da mensagem depende do servidor e da sua ferramenta (Cline, Aider, OpenCode e Continue envolvem os erros cada uma do seu jeito), então comece pelo número, depois confirme com a verificação curl abaixo.

401: a chave não corresponde ao endpoint#

A história clássica: você moveu uma ferramenta para um novo provedor, mudou a base URL e deixou a chave do provedor antigo na configuração. O endereço é novo, a chave é a antiga, e o servidor responde 401. Nada está quebrado; a chave apenas pertence a outra casa.

O que verificar:

1. Qual provedor emitiu a chave? Deve ser o mesmo cujo endereço você está chamando. Uma chave de um serviço não é válida em outro.
2. Caracteres perdidos. Um espaço ou uma quebra de linha colados junto com a chave, ou aspas que acabaram dentro do valor.
3. De onde a ferramenta a lê. Uma variável de ambiente definida em um terminal e não no terminal a partir do qual seu editor foi iniciado é uma causa frequente. Se a ferramenta tem tanto um arquivo de configuração quanto uma variável de ambiente, descubra qual prevalece.
4. Uma chave revogada ou excluída. Uma chave que você excluiu ou revogou para de funcionar — crie uma nova e coloque na configuração.

Se você não tem certeza de como as chaves funcionam ou onde guardá-las, o que é uma chave de API e como armazená-la com segurança cobre isso em palavras simples.

404 em todos os modelos: o endereço está errado#

A base URL do CheapTokens é https://api.cheaptokens.dev/v1. Ferramentas e SDKs acrescentam o caminho do endpoint por conta própria, então os deslizes usuais são sobre /v1:

• /v1 ausente: a ferramenta acaba chamando https://api.cheaptokens.dev/chat/completions.
• /v1 duplicado: você colou o caminho completo em um campo que já o adiciona, e obtém https://api.cheaptokens.dev/v1/v1/chat/completions.
• Variante errada: ferramentas no estilo OpenAI e o SDK da OpenAI usam o endereço com /v1. O SDK da Anthropic e o Claude Code usam o endereço sem /v1: https://api.cheaptokens.dev.

Se você já se perguntou o que exatamente é uma base URL e qual parte dela a ferramenta adiciona, este explicador percorre isso. Para o lado da Anthropic, veja o SDK Python da Anthropic com CheapTokens.

404 em um modelo: o id do modelo#

Este pega quem copia um nome de uma tabela de preços ou de outro provedor. Uma tabela de preços pode dizer DeepSeek-V4-Flash; a API quer o id completo do gateway, com o prefixo do desenvolvedor e a versão:

Ids curtos de rótulos de preço não são aceitos pela API, e a grafia importa: letras maiúsculas, a barra, o sufixo -0731. Copie o id da documentação do CheapTokens em vez de digitá-lo de memória — provedores diferentes nomeiam o mesmo modelo de formas diferentes. Para ver os ids exatos disponíveis para sua chave, chame GET https://api.cheaptokens.dev/v1/models com o mesmo cabeçalho Authorization e copie o id da lista:

curl https://api.cheaptokens.dev/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Se a lógica de nomes na tabela parecer estranha, como ler nomes de modelos de IA explica alias versus versão fixada.

Comprove a correção com um comando curl#

Tire a ferramenta da jogada e chame a API diretamente. Substitua o placeholder da chave pela sua própria:

curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [{"role": "user", "content": "Say hi in one word."}],
    "max_tokens": 20
  }'

Esta única requisição tem todos os três suspeitos: a chave no cabeçalho, a base URL na primeira linha, o id do modelo no corpo. Uma resposta JSON com um array choices significa que os três estão certos, e o que sua ferramenta faz de diferente é o problema. Se falhar, mude uma coisa por vez:

• 401 → troque pela chave que você obteve do CheapTokens e execute de novo.
• 404 → compare a URL caractere por caractere com a acima, depois o id do modelo.

Depois que o curl funcionar, copie os mesmos três valores para a ferramenta: a chave, a base URL (https://api.cheaptokens.dev/v1, ou sem /v1 para o SDK da Anthropic e o Claude Code) e o id completo do modelo.

Se ainda não funcionar#

• Mesmo erro na ferramenta, curl funciona. A ferramenta está lendo uma chave ou URL antiga de outro lugar: um segundo arquivo de configuração, um perfil salvo, uma variável de ambiente. Reinicie a ferramenta depois de alterá-la.
• Não tem certeza se o id do modelo está certo. Chame GET /v1/models com sua chave e copie o id da lista.
• Conexão recusada, timeouts, erros de certificado. Isso não é um 401 nem 404; veja erros de conexão comuns.
• Não tem certeza de como deve ser a primeira requisição. Sua primeira requisição à API vai passo a passo, e a documentação tem a referência completa.

O hábito que vale a pena manter: quando uma chamada falha, leia o número primeiro. 401 geralmente significa a chave, 404 geralmente o endereço ou o id do modelo, e o curl resolve. Isso esclarece a maioria desses erros antes de você abrir um único log.