Reliability and Routing10 de outubro de 2026Flatkey Team

Versão do Modelo Claude Não Encontrada: Corrija IDs de Modelo, Aliases e Rotas da API

Um guia prático de depuração para erros de versão do modelo Claude não encontrada em APIs nativas da Anthropic, routers, IDs de provedores de nuvem, configurações de agentes e fallbacks de produção.

Versão do Modelo Claude Não Encontrada: Corrija IDs de Modelo, Aliases e Rotas da API

Se você vir um erro Claude model version not found, não comece alterando o prompt. Comece comprovando três चीजas: o ID do modelo existe hoje, seu endpoint espera exatamente esse formato de ID e o workspace ou roteador que você está usando tem permissão para chamá-lo.

A correção rápida geralmente é uma destas:

Verificação	O que geralmente quebrou	Correção
ID do modelo	Um snapshot do Claude codificado estaticamente e desatualizado, um erro de digitação ou um nome de modelo copiado de outro provedor	Substitua por um alias atual da API Claude, como `claude-sonnet-5-5`, `claude-opus-5-5`, `claude-haiku-5-5` ou `claude-fable-5-1`, após verificar a lista atual de modelos da Anthropic.
Contrato do endpoint	Um ID específico do Bedrock, Vertex, Azure, compatível com OpenAI ou de gateway foi enviado para a API errada	Faça o modelo de string corresponder ao endpoint que você está chamando.
URL base	O SDK está apontando para o `base_url`, caminho ou rota errados	Confirme se o cliente está usando o Anthropic nativo `/v1/messages` ou uma rota compatível com OpenAI.
Acesso	O modelo existe, mas seu workspace, conta do provedor ou sub-chave não tem permissão para usá-lo	Verifique permissões de workspace, allowlists e acesso ao modelo antes de tentar novamente.
Estado de rollout	Um modelo recém-anunciado aparece na documentação, mas ainda não está presente no seu roteador ou implantação	Faça canary da rota e mantenha o modelo anterior que funcionava até que a nova rota passe.

Este guia fornece um runbook prático para falhas claude model version not found, claude model version e claude model versions em apps de produção, configurações do Claude Code, gateways e infraestrutura de agentes.

O que "Claude model version not found" significa

Claude model version not found geralmente é uma descrição, em nível de integração, de uma falha de resolução de modelo. Erros diretos da API da Anthropic são erros JSON estruturados. A Anthropic documenta 404 - not_found_error para um recurso solicitado que não pode ser encontrado, e seus corpos de erro incluem um error.type, error.message e ID da solicitação. A Messages API da Anthropic também exige um campo model que nomeia o modelo que completa o prompt.

Essa distinção importa. Uma resposta direta da API, uma exceção do SDK, um wrapper de gateway e uma CLI de agente podem todos expressar a mesma falha subjacente de forma diferente. Seu trabalho é preservar o status code bruto, error.type, message, request ID, string do modelo, caminho do endpoint e URL base antes de tentar novamente.

Use esta regra de triagem:

404 / not_found_error: verifique primeiro o caminho do endpoint, o identificador do modelo e os IDs de recursos.
400 / invalid_request_error: verifique se o modelo existe, mas rejeita uma configuração, tipo de ferramenta, modo de pensamento, prefill ou formato da solicitação.
401 / 403: verifique autenticação, acesso ao workspace e permissões do modelo.
"model version not found" específico de gateway: verifique tanto o catálogo de modelos do gateway quanto o ID do provedor upstream ao qual ele se mapeia.

Verificação do ID atual do modelo Claude

Antes de editar o código, compare a string do modelo com falha com a lista oficial atual. Até a documentação atual de modelos da Anthropic verificada para este artigo, os aliases visíveis da API Claude incluem:

Família	Alias da API Claude a verificar
Fable	`claude-fable-5-1`
Opus	`claude-opus-5-5`
Sonnet	`claude-sonnet-5-5`
Haiku	`claude-haiku-5-5`

Não assuma que um nome de modelo de um post de blog, rótulo de UI, marketplace de provedor ou amostra de código antiga é válido para toda interface de API. A documentação da Anthropic mostra IDs separados para a API Claude, Amazon Bedrock, Google Cloud, Microsoft Foundry e Claude Platform on AWS. Esses IDs podem parecer semelhantes, mas não são intercambiáveis.

Seis causas comuns

1. Uma versão do modelo Claude codificada estaticamente e desatualizada

IDs de modelo hard-coded envelhecem mal. Um serviço ainda pode conter um snapshot mais antigo, como:

const model = "claude-3-7-sonnet-20250219";

Se o endpoint não aceitar mais esse snapshot, ou se seu roteador nunca o mapeou, a solicitação pode falhar antes de o prompt ser avaliado. Substitua o valor codificado estaticamente por um alias atual que seu endpoint suporte e, em seguida, armazene esse alias em uma única fonte de configuração, em vez de arquivos dispersos.

const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-5-5";

Para sistemas de produção, registre tanto o alias configurado quanto a rota resolvida. Isso transforma o próximo incidente Claude model version not found em um diff de configuração, em vez de uma busca no código.

2. Um ID específico do provedor foi enviado para a API Claude

Plataformas de provedor usam seus próprios identificadores de modelo. Um ID no estilo Bedrock ou Vertex pode ser válido nesse provedor e inválido na API Claude nativa. O inverso também é verdadeiro: um alias nativo da API Claude pode não ser o identificador completo esperado por um runtime de provedor de nuvem.

Use esta tabela de contrato de endpoint:

Você está chamando	O ID do modelo deve ser algo como	Evite
Anthropic Claude API `/v1/messages`	Alias da API Claude da documentação da Anthropic, por exemplo `claude-sonnet-5-5`	IDs prefixados de Bedrock, Vertex ou Foundry
Amazon Bedrock	ID do modelo Bedrock mostrado na documentação ou no console do provedor	Aliases nativos somente para Claude quando o SDK espera IDs do Bedrock
Google Cloud / Vertex	ID do modelo do Google Cloud mostrado para essa implantação	IDs nativos ou do Bedrock colados de outro ambiente
Roteador compatível com OpenAI	ID do catálogo de modelos do roteador	Estruturas de requisição nativas da Anthropic, a menos que o roteador as suporte explicitamente
Roteador Flatkey	Uma rota suportada pelo Flatkey a partir do catálogo de modelos do Flatkey ou das instruções de configuração	Chaves de provedores dispersas e substituições por agente não revisadas

Se sua implantação abranger Anthropic direta, endpoints de provedores de nuvem e um roteador, mantenha uma pequena tabela de tradução na configuração:

routes:
  claude_primary:
    api_surface: anthropic_messages
    model: claude-sonnet-5-5
  claude_gateway:
    api_surface: openai_compatible_router
    model: claude-sonnet-5-5
  claude_bedrock:
    api_surface: bedrock
    model: anthropic.claude-sonnet-5-5

As strings exatas devem vir do provedor ou roteador que você estiver usando. O objetivo é tornar explícita a superfície da API.

3. A URL base e o SDK não correspondem

O SDK da Anthropic espera o contrato da Messages API da Anthropic. Um roteador compatível com OpenAI espera um cliente e um payload compatíveis com OpenAI, a menos que documente uma rota compatível com Anthropic. Se o cliente, o caminho e o campo de modelo estiverem misturados, o erro pode parecer uma versão do modelo Claude ausente, mesmo quando o problema real é a rota errada.

Verifique estes campos em conjunto:

SDK/cliente:        SDK da Anthropic, SDK da OpenAI, Claude Code, Cursor, Cline, HTTP personalizado
URL base:           provedor direto, roteador, proxy de staging, mock local
Caminho:            /v1/messages, /v1/chat/completions, caminho de runtime específico do provedor
Formato do ID do modelo:   alias nativo do Claude, ID do provedor de nuvem, ID do catálogo do roteador
Cabeçalho de autenticação:        x-api-key, Authorization: Bearer, assinatura específica do provedor

Se uma linha pertencer a uma superfície de API diferente, corrija isso antes de tentar novamente.

4. Um novo alias do Claude ainda não chegou ao seu roteador

Lançamentos de modelos não são atômicos em todos os SDKs, proxies, provedores de nuvem e gateways. Um modelo pode aparecer em um catálogo antes de sua rota, lista de अनुमति, ou implantação oferecer suporte a ele.

Use um canary em vez de mudar o tráfego de produção imediatamente:

model_canary:
  candidate_model: claude-sonnet-5-5
  previous_model: claude-sonnet-5
  checks:
    - solicitação mínima sem streaming
    - solicitação com streaming se seu app usa streaming
    - solicitação de tool-call se seu app usa ferramentas
    - caminho de contagem de tokens ou dry-run, se disponível
    - linha de faturamento e registro de uso
  rollout:
    start: 1%
    promote_when: 100 successful requests and no model-resolution errors
    rollback_on: any repeated not_found_error or route mismatch

É aqui que o roteamento e a visão de ledger do Flatkey ajudam. Se o Claude for apenas uma rota entre muitos modelos, use um catálogo de modelos, uma revisão de rota base e um ledger de uso, em vez de depurar consoles separados de provedores e configurações separadas de agentes.

5. Permissões do workspace ou allowlists de modelos bloqueiam o acesso

Às vezes a string do modelo é válida, mas sua chave não consegue chamá-lo. Isso pode acontecer no workspace do provedor, na conta de nuvem, no roteador ou na camada de subchave.

Verifique:

Se a chave de API pertence ao workspace que você espera.
Se o modelo está habilitado para esse workspace.
Se uma subchave de gateway, chave de ambiente ou chave de agente tem uma allowlist de modelos.
Se as chaves de staging e produção têm acesso diferente aos modelos.
Se limites de gasto ou controles de política estão retornando um erro com formato de permissão.

Não resolva falhas de acesso ampliando todas as chaves. Crie uma política restrita que diga quais agentes e ambientes podem chamar cada versão do modelo Claude.

6. O modelo existe, mas sua solicitação usa recursos de modelo sem suporte

Os documentos de erro da Anthropic listam várias falhas de validação em que o modelo é real, mas a estrutura da solicitação é inválida. Exemplos incluem diferenças no modo de pensamento, configurações forçadas de uso de ferramentas, suporte a tipos de ferramentas e mensagens de assistant pré-preenchidas em modelos mais novos.

Se o status for 400 invalid_request_error, pare de procurar por uma versão de modelo ausente. Em vez disso, compare o corpo da solicitação com as regras de capacidade atuais do modelo. A correção pode ser alterar thinking, tool_choice, as declarações de ferramentas ou o tratamento do histórico de mensagens, em vez de alterar model.

Um runbook de depuração em produção

Passo 1: Capture o registro completo da solicitação com falha

Salve um registro mínimo de depuração antes de editar qualquer coisa:

{
  "provider": "anthropic_or_router_name",
  "base_url": "https://api.example.com",
  "path": "/v1/messages",
  "model": "claude-sonnet-5-5",
  "sdk": "anthropic-typescript",
  "status": 404,
  "error_type": "not_found_error",
  "request_id": "req_...",
  "environment": "production",
  "api_key_scope": "prod-agent-key"
}

Se você usa a Flatkey, também capture a rota, a sub-chave, a linha do ledger de uso e qualquer decisão de fallback. Se você usa a Anthropic diretamente, mantenha o valor de request-id da resposta, porque a Anthropic pede esse identificador em casos de suporte.

Passo 2: Reproduza com a menor solicitação possível

Remova ferramentas, histórico longo, imagens, blocos de pensamento em cache e wrappers de framework. Teste uma única mensagem curta com o mesmo modelo e a mesma chave.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [
      {"role": "user", "content": "Responda com ok."}
    ]
  }'

Se a solicitação mínima funcionar, a versão do modelo existe para essa chave e esse endpoint. Passe para a depuração da forma da solicitação. Se falhar com o mesmo resultado de não encontrado, concentre-se na string do modelo, no endpoint ou na camada de acesso.

Passo 3: Padronize os IDs de modelo em um só lugar

Crie uma única fonte de configuração para as versões de modelo Claude:

models:
  claude_default:
    owner: platform
    api_surface: anthropic_messages
    model: claude-sonnet-5-5
    fallback: claude-haiku-5-5
    last_verified: "2026-10-10"
  claude_reasoning:
    owner: agents
    api_surface: anthropic_messages
    model: claude-opus-5-5
    fallback: claude-sonnet-5-5
    last_verified: "2026-10-10"

Depois, bloqueie IDs de modelo brutos no código da aplicação. O app deve solicitar claude_default, e não colar uma nova versão do modelo Claude em cinco serviços.

Passo 4: Verifique a configuração de agentes e CI

Erros de versão do modelo Claude não encontrada geralmente vêm de uma variável de ambiente esquecida, e não de uma alteração de código. Inspecione:

.env, .env.production e os valores do gerenciador de segredos.
Variáveis do Claude Code, Cursor, Cline, Roo, Aider e GitHub Actions.
Padrões da imagem Docker e mapas de configuração do Kubernetes.
Listas de permissão de modelo por sub-chave para cliente ou equipe.
Substituições de desenvolvimento local que foram copiadas para produção.

Se sua equipe usa o Claude Code por meio de um gateway, verifique também a autenticação e a configuração da URL base. Um ANTHROPIC_BASE_URL incorreto ou um escopo de chave inadequado pode tornar o diagnóstico do modelo confuso; use o guia de erros de token de autenticação do Claude Code quando a autenticação também estiver falhando.

Passo 5: Decida se deve tentar novamente, fazer fallback ou falhar de forma fechada

Não tente novamente para sempre um erro determinístico de modelo ausente. Use esta política:

Padrão de erro	Repetir?	Fallback?	Ação humana
ID de modelo com erro de digitação ou desatualizado	Não	Somente após a configuração ser corrigida	Atualizar o registro de modelos e fazer o redeploy
Nova alias ainda não no roteador	Sem novas tentativas repetidas	Manter o modelo verificado anterior	Abrir tarefa de habilitação/canário da rota
Workspace sem acesso	Não	Talvez, se existir um fallback aprovado	Corrigir a chave, o workspace ou a allowlist
400 incompatibilidade de forma da solicitação	Não	Não até a solicitação ser corrigida	Corrigir o corpo da solicitação ou as flags de recurso
529 sobrecarregado ou interrupção transitória do upstream	Sim, com backoff limitado	Sim, se a política de fallback permitir	Monitorar a saúde da rota

Para o tratamento de sobrecarga transitória, use um runbook diferente: Erro de API 529 sobrecarregado. Uma falha de versão de modelo geralmente é determinística até que você altere a configuração.

Checklist de revisão de rota da Flatkey

Quando o Claude faz parte de um sistema multimodelo, um roteador lhe dá um único lugar para revisar nomes de modelo, chaves, allowlists, gastos e fallbacks. O posicionamento da Flatkey é uma chave, um saldo, uma fatura, endpoints oficiais de modelo e um ledger de uso compartilhado entre modelos e ferramentas.

Use esta checklist antes de promover uma nova rota Claude:

route_review:
  route_name: claude_primary
  current_model: claude-sonnet-5-5
  endpoint_contract: openai_compatible_or_anthropic_native
  owner: platform
  environments:
    dev: verified
    staging: verified
    production: canary
  controls:
    sub_key_allowlist: true
    request_ledger: true
    fallback_policy: explicit
    usage_alert: true
  rollback:
    previous_model: claude-sonnet-5
    trigger: repeated model-resolution errors

Para um design de rota mais amplo, leia proxy de API Claude vs roteador multimodelo e o guia de catálogo de modelos de IA. Para trade-offs de custo e roteamento, combine este artigo com preços da API Claude e roteamento de fallback para APIs de LLM.

Checklist de incidente copiável

Use isto no Slack, Linear, GitHub ou no seu documento de incidente:

## Incidente: versão do modelo Claude não encontrada

- String do modelo com falha:
- Superfície da API: Anthropic nativa / roteador / Bedrock / Vertex / outro
- URL base:
- Caminho da solicitação:
- SDK ou cliente:
- Código de status:
- error.type:
- request-id:
- Primeiro deploy com falha:
- Alias oficial atual do modelo verificado:
- A solicitação mínima passa?
- O modelo está habilitado para este workspace/chave/sub-chave?
- Isto é um erro de recurso sem suporte em vez de modelo não encontrado?
- Modelo de rollback:
- Responsável:

Mantenha a checklist simples e sem drama. O objetivo é evitar que uma versão ausente do modelo Claude se transforme em um incidente amplo, em que cada equipe altera uma configuração diferente.

Perguntas frequentes

“Claude model version not found” é o mesmo que um 404?

Frequentemente, mas nem sempre. A Anthropic documenta 404 - not_found_error para recursos ausentes, enquanto SDKs e gateways podem reformular a mensagem. Preserve o status code bruto e error.type antes de decidir.

Quais versões do modelo Claude devo usar?

Use os aliases atuais do modelo a partir da API ou da superfície do provedor que você está chamando. Não copie uma versão do modelo Claude de outro provedor de nuvem, roteador ou exemplo de código antigo sem verificar o catálogo desse endpoint.

Devo usar um alias ou um snapshot datado?

Para a maioria das equipes de aplicação, um alias atual é mais fácil de operar porque o provedor controla o mapeamento suportado. Se você precisar de reprodutibilidade rigorosa, documente a política exata de snapshot, o plano de aposentadoria e o caminho de rollback.

O Flatkey pode corrigir `Claude model version not found` automaticamente?

O Flatkey não pode tornar válido um ID de modelo upstream inválido, mas pode reduzir os lugares onde IDs incorretos ficam escondidos. Use o Flatkey para centralizar a revisão do catálogo de modelos, roteamento com uma chave, allowlists de subchaves, logs de uso e política de fallback quando o Claude for apenas uma rota de modelo entre várias.

Quando devo fazer fallback para outro modelo?

O fallback é apropriado depois que você classificar a falha. Não faça fallback em caso de erro de digitação, URL base errada ou chave não autorizada. Faça fallback quando sua política disser que a rota atual está indisponível e a próxima rota tiver passado pelas mesmas verificações de entrada, qualidade e custo.

Verificação final

Antes de encerrar um ticket de claude model version not found, confirme a correção em três lugares: configuração de origem, teste de smoke da API mínima e logs de rota de produção. Em seguida, adicione a versão funcional do modelo Claude ao seu registro de modelos para que a próxima implantação não reintroduza a mesma string desatualizada.

Se você já estiver roteando vários modelos, teste a mesma mudança pelo Flatkey para que seu ledger de requisições, a política de fallback e as allowlists de modelos concordem antes que o tráfego de produção seja movido.