Erros e confiabilidade

Model Not Found: como diagnosticar e corrigir o erro de API

Rastreie um erro model not found por endpoint, protocolo, API Key, Model ID, aliases, overrides, status e request ID.

BT

BetterToken

Equipe editorial
6 min de leitura

O erro model not found significa que o servidor não conseguiu resolver a Model ID especificada no contexto do endpoint e da API Key atuais. A causa pode ser erro de digitação, alias desatualizado, protocolo incorreto, falta de acesso ou override de configuração. Anote status e request ID, depois confira a cadeia da Base URL à chave e ao modelo. Escolher nomes aleatoriamente apenas esconde o erro original.

O que salvar antes de mudar a configuração

Primeiro registre um cartão de diagnóstico curto:

time: 2026-08-03T12:00:00Z
client: your-client-and-version
protocol: openai-compatible | anthropic-compatible
base_url: https://example.com/v1
model: MODEL_ID_FROM_CONFIG
http_status: 404
provider_code: model_not_found
request_id: req_...

API Key, prompt completo e resposta não devem entrar no cartão. Se o erro ocorreu no IDE ou ferramenta Agent, anote separadamente o arquivo de configuração e se há variáveis de ambiente. Isso permite entender qual valor realmente chegou ao servidor.

Quer repetir o diagnóstico com o catálogo atual? Você pode criar sua própria conta BetterToken e API Key, conferir endpoint e Model ID na referência de API e executar uma solicitação mínima. Na BetterToken, tipo de endpoint, Base URL, grupo de Key e Model ID atual devem corresponder. Use o nome atual da documentação ou da página de modelos e preços e confira o resultado no Dashboard.

Etapa 1: conferir Base URL e caminho

Veja a URL final da solicitação, não apenas a linha de configurações. O SDK pode adicionar sozinho /v1, /models, /chat/completions, /responses ou /messages.

Erros típicos:

  • Base URL já contém caminho de recurso e SDK o adiciona novamente;
  • /v1 está ausente ou duplicado;
  • cliente OpenAI envia para endereço Anthropic-compatible;
  • variável de ambiente sobrescreve Base URL da configuração;
  • aplicação usa outro perfil ou workspace.

Para BetterToken OpenAI-compatible, as ferramentas usam Base URL com /v1; Anthropic SDK e Claude Code usam endereço sem /v1, e o caminho Messages completo é gerado à parte. Antes de corrigir, consulte a página atual da ferramenta específica.

Etapa 2: conferir qual API Key é realmente usada

A mesma interface pode armazenar várias credenciais. Um erro de modelo às vezes oculta a falta de acesso da Key escolhida.

Confira:

  1. credential ou variável de ambiente de que o cliente lê a chave;
  2. ausência de espaços ou quebras de linha extras;
  3. correspondência da Key com protocolo e grupo de modelos;
  4. se configuração do projeto sobrescreve ajuste global;
  5. se a Key expirou ou foi revogada.

Não imprima a chave via echo, log de depuração ou captura. Para comparar credenciais, nome seguro de perfil ou últimos caracteres de fingerprint bastam se a interface os mostrar.

Etapa 3: obter a Model ID atual

Um endpoint OpenAI-compatible muitas vezes possui lista de modelos. Uma solicitação segura de diagnóstico é:

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

O comando usa variáveis de ambiente e não contém a chave real. Só é adequado quando a documentação do endpoint confirma /models.

Para outro protocolo ou cliente, use o diretório oficial do provider. Copie o campo id sem mudar maiúsculas, espaços ou sufixos. Nome comercial e API Model ID podem ser diferentes.

Se a lista abrir, mas o modelo desejado não estiver nela, confira Key e catálogo. Se /models retornar erro, corrija primeiro endpoint ou autorização.

Etapa 4: encontrar alias e configuração legada

A Model ID pode vir de várias fontes:

  • configuração de projeto;
  • configuração global do cliente;
  • variável de ambiente;
  • perfil de UI;
  • flag de linha de comando;
  • sessão salva;
  • gateway de routing ou mapping de modelo.

Pesquisar no repositório ajuda a achar o valor antigo:

rg -n --hidden --glob '!node_modules' --glob '!.git' \
  'OLD_MODEL_ID|model[[:space:]]*=' .

A busca também pode encontrar arquivos de configuração com segredos. Não publique a saída completa. Corrija apenas a fonte lida pelo cliente.

Ferramentas de AI costumam priorizar “configuração de projeto sobre global”. Após mudar, reinicie o cliente ou abra sessão nova se ele armazena settings de provider em cache.

Etapa 5: separar erro de modelo de erro de acesso

Códigos HTTP de APIs compatíveis não precisam coincidir, portanto examine também o corpo do erro.

  • 401: confira primeiro credential e formato de autorização.
  • 403: o modelo pode existir, mas a Key atual não tem acesso.
  • 404: possível erro de caminho, endpoint ou Model ID.
  • 400: o servidor pode ter rejeitado model ou outro parâmetro.
  • 429 / 5xx: geralmente é outra categoria; não mude Model ID sem sinal adicional.

A frase model not found na UI pode ser paráfrase do cliente. Encontre status HTTP, código provider e request ID originais.

Reteste mínimo

Depois da correção, envie uma solicitação curta sem streaming e ferramentas. Para Chat Completions OpenAI-compatible, o esquema pode ser:

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_CURRENT_CATALOG",
    "messages": [{"role": "user", "content": "Reply with OK"}],
    "max_tokens": 8
  }'

Campos e endpoint devem corresponder à documentação do provider. Não transfira este exemplo para Anthropic Messages sem adaptação.

Uma verificação bem-sucedida tem quatro correspondências:

  • status HTTP significa sucesso;
  • resposta indica a Model ID esperada ou versão documentada;
  • solicitação apareceu no Dashboard;
  • horário, status e uso coincidem com o teste.

Se a consulta curta funciona e IDE continua a mostrar model not found, a configuração do servidor já foi corrigida. Procure override ou cache no cliente.

Checklist curto

  • Status, código provider e request ID salvos.
  • URL final conferida sem /v1 e caminho de recurso duplicados.
  • Cliente usa credential esperada.
  • Model ID veio do catálogo atual.
  • Overrides de projeto, globais e de ambiente conferidos.
  • Uma solicitação mínima sem ferramentas e stream foi executada.
  • Solicitação foi relacionada ao Dashboard.

Na BetterToken, confira a referência de API e o catálogo de modelos atual antes de trocar Model ID. É mais rápido e seguro que procurar nomes parecidos.

FAQ

Por que o modelo aparece no site, mas a API retorna model not found?

Pode haver protocolo, grupo de Key, região de catálogo, sessão antiga diferentes ou diferença entre nome comercial e API ID. Confira a lista de modelos especificamente para o credential atual.

Repetir a solicitação ajuda?

Não em caso de erro de digitação ou endpoint incorreto. Primeiro corrija a configuração. Retry só é adequado para erro temporário quando status e código provider confirmam isso.

Posso salvar a lista de modelos na configuração para sempre?

Guarde a ID escolhida como setting gerenciado e compare-a periodicamente com o catálogo atual. Disponibilidade e aliases podem mudar.

Por que curl funciona mas a aplicação não?

A aplicação pode ler outra Base URL, outro credential ou outra Model ID. Compare a solicitação final e confira override de projeto, variáveis de ambiente e perfil salvo.

Fontes

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.