Os IDs de modelo não são portáveis: api.anthropic.com exige IDs datados, o Gemini usa suas próprias strings de versão e cada gateway define seus slugs. Um 404 aqui significa “este host não tem um modelo com exatamente essa string” — a correção é sempre perguntar ao endpoint o que ele oferece.
O erro
{
"error": {
"type": "model_not_found",
"message": "The model 'claude-sonnet' does not exist or you do not have access to it.",
"code": "model_not_found"
}
}Causas e soluções em resumo
| Causa | Solução |
|---|---|
| ID de modelo de outro host | Cada API tem seu próprio namespace — copie os IDs da lista de modelos do próprio endpoint, não de publicações em blogs. |
| Versão obsoleta/renomeada | Os provedores aposentam snapshots datados; fixe um ID atual e assine as notas de descontinuação. |
| Slug com erro de digitação ou truncado | claude-sonnet não é um modelo em lugar algum; as strings exatas importam. |
| O modelo existe, mas está desabilitado para sua chave/plano | Alguns hosts restringem modelos por plano — o endpoint de listagem mostra o que SUA chave pode chamar. |
Liste os modelos do endpoint que você está chamando
GET /v1/models é a fonte de verdade em qualquer host compatível com OpenAI — ele retorna exatamente os IDs que sua chave pode usar:
curl -s https://api.kunavo.com/v1/models \
-H "Authorization: Bearer $KUNAVO_API_KEY" \
| python3 -c "import json,sys; print('\n'.join(m['id'] for m in json.load(sys.stdin)['data']))"Resolva modelos em tempo de execução, não de forma fixa
Os catálogos mudam (novos snapshots, aposentadorias). Resolva a lista de modelos na inicialização, prefira slugs configurados com um fallback e alerte quando um slug configurado desaparecer de /v1/models, em vez de gerar 404 em produção.
Se você estiver chamando pela Kunavo
O Kunavo usa slugs estáveis e legíveis (claude-sonnet-5, gpt-5-6-terra, claude-fable-5), listados em GET /v1/models com metadados por modelo; slugs aposentados redirecionam 301 para seus sucessores nas páginas de modelos do site, para que os links não quebrem. O endpoint de listagem é autoritativo — o llms.txt informa o mesmo a qualquer agente que o leia.
Perguntas frequentes
Por que o mesmo ID de modelo funciona em uma API e retorna 404 em outra?
Porque os IDs têm namespace por host: os IDs datados da Anthropic, os nomes versionados do Gemini e os slugs de cada gateway são strings diferentes para modelos relacionados. Sempre copie da própria lista de modelos do endpoint de destino.
Como me preparar para a aposentadoria de modelos?
Resolva /v1/models na inicialização, mantenha o ID do modelo na configuração (não no código), defina uma cadeia de fallback e avise-se quando um ID configurado desaparecer — isso transforma um 404 de produção em uma alteração de configuração.
Guias relacionados
Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.