Anthropic API 404 not_found_error: "model: …" — por que um nome de modelo existente ainda retorna 404

A parte confusa desse 404 é que o modelo geralmente existe — na documentação da Anthropic, em uma publicação de blog ou no código do trimestre passado. O que não existe é a lista de modelos que sua chave de API está autorizada a endereçar hoje.

O erro

resposta (HTTP 404)

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: claude-3-5-sonnet"
  }
}

Causas e soluções em resumo

Causa	Solução
Um snapshot datado aposentado	Snapshots são descontinuados conforme um cronograma publicado e depois deixam de ser resolvidos. Migre para um atual.
Um alias que nunca existiu	`claude-3-5-sonnet` é uma família, não um ID chamável. Os IDs da Anthropic incluem uma versão ou um sufixo de data.
O modelo é real, mas não está habilitado para sua conta	Modelos mais recentes podem ser restritos por nível. O 404 é indistinguível de um erro de digitação — consulte o endpoint de modelos, não a documentação.
Um nome de modelo da OpenAI em um endpoint da Anthropic	`gpt-4o` em api.anthropic.com significa modelo ausente, não erro de roteamento. Use um gateway se quiser um único endpoint para ambos.

Consulte a API, não a documentação

A documentação descreve o catálogo; o endpoint de modelos descreve o seu catálogo. Quando os dois divergem, o endpoint está correto. Tudo que estiver ausente dessa lista retornará 404, por mais atual que pareça em outro lugar.

list-models.sh

curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  | grep '"id"'

Fixe deliberadamente, atualize deliberadamente

Codificar um snapshot datado garante reprodutibilidade e um futuro 404 em uma data que você não escolheu. Ler o ID do modelo da configuração significa que a correção é um valor definido no deploy, não uma alteração de código — e essa mesma troca permite fazer failover quando um modelo está ocupado, em vez de ausente.

model_config.py

import os

# One place to change when a snapshot retires.
MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)

Diferencie 404 de 400 e 403

404 significa que o nome não resolveu para nada. 400 significa que o nome estava correto, mas a solicitação não estava (parâmetro inválido, conteúdo malformado). 403 significa que o modelo existe, mas você não pode usá-lo. Apenas 404 é corrigido alterando a string do modelo.

Se você estiver chamando pela Kunavo

O catálogo da Kunavo é a lista retornada pelo endpoint /v1/models, e cada ID nela pode ser chamado com qualquer chave com saldo — não há restrição de modelos por conta, portanto a causa “real, mas não habilitado para você” acima não ocorre. Como o mesmo endpoint atende nomes do Claude e da família GPT, um ID da OpenAI também não é um erro de endpoint incorreto; ele simplesmente é roteado. Ainda ocorrem descontinuações upstream e, quando um modelo é retirado, seu ID é redirecionado ou documentado, em vez de ser deixado retornar 404 silenciosamente. Os IDs atuais e suas tarifas por token estão na lista de preços da Claude API.

Perguntas frequentes

O 404 alguma vez é um erro temporário?

Não. Ao contrário de 429, 500 e 529, repetir um 404 com a mesma string de modelo só pode falhar novamente. Altere a string ou pare.

Como sei quando um snapshot será aposentado?

A Anthropic publica datas de descontinuação para snapshots datados. Se você fixa snapshots, esse cronograma é um item de calendário; se lê o ID da configuração, é uma alteração de uma linha.

Por que a chave do meu colega funciona com o mesmo nome?

A disponibilidade dos modelos pode variar conforme o nível da conta. Compare as duas respostas de /v1/models — essa diferença é a resposta.

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.