Versión del modelo Claude no encontrada: corrige IDs de modelo, alias y rutas de API incorrectos

Versión del modelo Claude no encontrada: corrige IDs de modelo, alias y rutas de API incorrectos

Si ves el error Claude model version not found, no empieces cambiando el prompt. Empieza demostrando tres cosas: que el ID del modelo existe hoy, que tu endpoint espera exactamente ese formato de ID y que el workspace o router que estás usando tiene अनुमति para llamarlo.

La solución rápida suele ser una de estas:

Comprobación	Qué se rompió normalmente	Solución
ID del modelo	Una instantánea de Claude codificada de forma rígida y desactualizada, un error tipográfico o un nombre de modelo copiado de otro proveedor	Reemplázalo por un alias actual de la API de Claude, como claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5 o claude-fable-5-1, después de comprobar la lista actual de modelos de Anthropic.
Contrato del endpoint	Se envió a la API incorrecta un ID específico de Bedrock, Vertex, Azure, OpenAI-compatible o de un gateway	Haz coincidir la cadena del modelo con el endpoint al que estás llamando.
URL base	El SDK apunta al base_url, ruta o endpoint incorrectos	Confirma si el cliente está usando el nativo de Anthropic /v1/messages o una ruta compatible con OpenAI.
Acceso	El modelo existe, pero tu workspace, cuenta del proveedor o subclave no tiene permiso para usarlo	Comprueba los permisos del workspace, las allowlists y el acceso al modelo antes de reintentar.
Estado del despliegue	Un modelo anunciado recientemente es visible en la documentación, pero todavía no está presente en tu router o despliegue	Haz canary de la ruta y mantén el modelo funcional anterior hasta que la nueva ruta pase.

Esta guía te ofrece un runbook práctico para fallos de claude model version not found, claude model version y claude model versions en aplicaciones de producción, configuraciones de Claude Code, gateways e infraestructura de agentes.

Qué significa "Claude model version not found"

Claude model version not found suele ser una descripción a nivel de integración de un fallo de resolución del modelo. Los errores directos de la API de Anthropic están estructurados como errores JSON. Anthropic documenta 404 - not_found_error para un recurso solicitado que no se puede encontrar, y sus cuerpos de error incluyen un error.type, error.message y un ID de solicitud. La Messages API de Anthropic también requiere un campo model que nombre el modelo que completa el prompt.

Esa distinción importa. Una respuesta directa de la API, una excepción del SDK, un wrapper de gateway y una CLI de agente pueden formular el mismo fallo subyacente de manera diferente. Tu trabajo es conservar el código de estado en bruto, error.type, message, el ID de solicitud, la cadena del modelo, la ruta del endpoint y la URL base antes de reintentar.

Usa esta regla de triaje:

• 404 / not_found_error: comprueba primero la ruta del endpoint, el identificador del modelo y los IDs de recurso.
• 400 / invalid_request_error: comprueba si el modelo existe pero rechaza una configuración, tipo de herramienta, modo de pensamiento, prefill o forma de solicitud.
• 401 / 403: comprueba la autenticación, el acceso al workspace y los permisos del modelo.
• "model version not found" específico del gateway: comprueba tanto el catálogo de modelos del gateway como el ID del proveedor upstream al que se asigna.

Comprobación del ID actual del modelo Claude

Antes de editar código, compara la cadena del modelo que falla con la lista oficial actual. Según la documentación actual de modelos de Anthropic comprobada para este artículo, los alias visibles de la API de Claude incluyen:

Familia	Alias de la API de Claude que verificar
Fable	claude-fable-5-1
Opus	claude-opus-5-5
Sonnet	claude-sonnet-5-5
Haiku	claude-haiku-5-5

No asumas que un nombre de modelo de una entrada de blog, una etiqueta de UI, un marketplace de proveedor o un ejemplo de código antiguo sea válido para todas las superficies de la API. La documentación de Anthropic muestra IDs separados para la API de Claude, Amazon Bedrock, Google Cloud, Microsoft Foundry y Claude Platform en AWS. Esos IDs pueden parecer similares, pero no son intercambiables.

Seis causas comunes

1. Una versión del modelo Claude codificada de forma rígida y desactualizada

Los IDs de modelo codificados envejecen mal. Un servicio todavía puede contener una instantánea antigua como:

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

Si el endpoint ya no acepta esa instantánea, o tu router nunca la mapeó, la solicitud puede fallar antes de que se evalúe el prompt. Reemplaza el valor codificado de forma rígida por un alias actual que tu endpoint admita y luego guarda ese alias en una sola fuente de configuración en lugar de repartirlo entre varios archivos.

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

Para sistemas de producción, registra tanto el alias configurado como la ruta resuelta. Eso hace que el siguiente incidente de Claude model version not found sea una diferencia de configuración en lugar de una búsqueda en el código.

2. Se envió a la API de Claude un ID específico del proveedor

Las plataformas de proveedores usan sus propios identificadores de modelo. Un ID estilo Bedrock o estilo Vertex puede ser válido en ese proveedor e inválido frente a la API nativa de Claude. Lo contrario también es cierto: un alias nativo de la API de Claude puede no ser el identificador completo que espera un runtime de proveedor en la nube.

Usa esta tabla de contrato del endpoint:

Estás llamando	El ID del modelo debería verse como	Evita
Anthropic Claude API /v1/messages	Alias de la API de Claude en la documentación de Anthropic, por ejemplo claude-sonnet-5-5	IDs con prefijo de Bedrock, Vertex o Foundry
Amazon Bedrock	ID del modelo de Bedrock mostrado en la documentación o consola del proveedor	Alias nativos solo de Claude cuando el SDK espera IDs de Bedrock
Google Cloud / Vertex	ID del modelo de Google Cloud mostrado para ese despliegue	IDs nativos o de Bedrock pegados desde otro entorno
Router compatible con OpenAI	El ID del catálogo de modelos del router	Formas de solicitud nativas de Anthropic, a menos que el router las admita explícitamente
Router Flatkey	Una ruta compatible con Flatkey desde el catálogo de modelos de Flatkey o las instrucciones de configuración	Claves de proveedor dispersas y anulaciones por agente sin revisar

Si tu despliegue abarca Anthropic directo, endpoints de proveedores en la nube y un router, mantén una pequeña tabla de traducción en la configuración:

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

Las cadenas exactas deben provenir del proveedor o router que estés usando. La idea es hacer explícita la superficie de la API.

3. La URL base y el SDK no coinciden

El SDK de Anthropic espera el contrato de la Messages API de Anthropic. Un router compatible con OpenAI espera un cliente y un payload compatibles con OpenAI, a menos que documente una ruta compatible con Anthropic. Si se mezclan el cliente, la ruta y el campo del modelo, el error puede parecer una versión de modelo Claude faltante incluso cuando el problema real es la ruta incorrecta.

Comprueba estos campos juntos:

SDK/cliente:        SDK de Anthropic, SDK de OpenAI, Claude Code, Cursor, Cline, HTTP personalizado
URL base:           proveedor directo, router, proxy de staging, mock local
Ruta:               /v1/messages, /v1/chat/completions, ruta de runtime específica del proveedor
Formato del ID del modelo: alias nativo de Claude, ID del proveedor en la nube, ID del catálogo del router
Encabezado de auth: x-api-key, Authorization: Bearer, firma específica del proveedor

Si una línea pertenece a una superficie de API diferente, corrígelo antes de volver a intentar.

4. Un nuevo alias de Claude aún no ha llegado a tu router

Los lanzamientos de modelos no son atómicos en todos los SDK, proxies, proveedores cloud y gateways. Un modelo puede aparecer en un catálogo antes de que tu ruta, lista de अनुमति, o despliegue lo admita.

Usa un canary en lugar de cambiar el tráfico de producción de inmediato:

model_canary:
  candidate_model: claude-sonnet-5-5
  previous_model: claude-sonnet-5
  checks:
    - solicitud mínima sin streaming
    - solicitud con streaming si tu app hace streaming
    - solicitud de llamada a herramienta si tu app usa herramientas
    - recuento de tokens o ruta de simulación si está disponible
    - fila de facturación y registro de uso
  rollout:
    start: 1%
    promote_when: 100 solicitudes exitosas y ningún error de resolución de modelo
    rollback_on: cualquier not_found_error repetido o desajuste de ruta

Ahí es donde ayudan el enrutamiento y la vista de libro mayor de Flatkey. Si Claude es una ruta entre muchos modelos, usa un catálogo de modelos, una revisión de ruta base y un libro mayor de uso en lugar de depurar consolas de proveedor separadas y configuraciones de agentes separadas.

5. Los permisos del workspace o las listas de अनुमति de modelos bloquean el acceso

A veces la cadena del modelo es válida, pero tu clave no puede llamarla. Eso puede ocurrir en el workspace del proveedor, la cuenta cloud, el router o la capa de subclave.

Comprueba:

• Si la API key pertenece al workspace que esperas.
• Si el modelo está habilitado para ese workspace.
• Si una subclave del gateway, una clave de entorno o una clave de agente tiene una lista de अनुमति de modelos.
• Si las claves de staging y producción tienen diferente acceso a modelos.
• Si los límites de gasto o los controles de políticas están devolviendo un error con forma de permiso.

No resuelvas fallos de acceso ampliando todas las claves. Crea una política restringida que diga qué agentes y entornos pueden llamar a cada versión del modelo Claude.

6. El modelo existe, pero tu solicitud usa funciones de modelo no admitidas

La documentación de errores de Anthropic enumera varias fallas de validación en las que el modelo es real pero la forma de la solicitud es inválida. Los ejemplos incluyen diferencias en el modo de pensamiento, ajustes forzados de uso de herramientas, compatibilidad del tipo de herramienta y mensajes de asistente rellenados previamente en modelos más nuevos.

Si el estado es 400 invalid_request_error, deja de buscar una versión de modelo faltante. Compara el cuerpo de la solicitud con las reglas actuales de capacidades del modelo. La solución puede ser cambiar thinking, tool_choice, las declaraciones de herramientas o el manejo del historial de mensajes en lugar de cambiar model.

Un runbook de depuración en producción

Paso 1: Captura el registro completo de la solicitud fallida

Guarda un registro mínimo de depuración antes de editar nada:

{
  "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"
}

Si usas Flatkey, captura también la ruta, la subclave, la fila del libro mayor de uso y cualquier decisión de fallback. Si usas Anthropic directamente, conserva el valor request-id de la respuesta porque Anthropic pide ese identificador en los casos de soporte.

Paso 2: Reproduce con la solicitud más pequeña

Elimina herramientas, historial largo, imágenes, bloques de pensamiento en caché y envoltorios del framework. Prueba un mensaje corto con el mismo modelo y la misma clave exactos.

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": "Reply with ok."}
    ]
  }'

Si la solicitud mínima funciona, la versión del modelo existe para esa clave y ese endpoint. Pasa a depurar la forma de la solicitud. Si falla con el mismo resultado de no encontrado, céntrate en la cadena del modelo, el endpoint o la capa de acceso.

Paso 3: Normaliza los IDs de modelo en un solo lugar

Crea una única fuente de configuración para las versiones del 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"

Después, bloquea los IDs de modelo sin formato en el código de la aplicación. La app debería pedir claude_default, no pegar una nueva versión del modelo Claude en cinco servicios.

Paso 4: Revisa la configuración de agentes y CI

Los errores de modelo Claude no encontrado suelen venir de una variable de entorno olvidada más que de un cambio de código. Inspecciona:

• .env, .env.production y los valores del gestor de secretos.
• Variables de Claude Code, Cursor, Cline, Roo, Aider y GitHub Actions.
• Valores predeterminados de imágenes Docker y mapas de configuración de Kubernetes.
• Listas de permitidos de modelos por subclave para cada cliente o equipo.
• Invalidaciones de desarrollo local que se copiaron en producción.

Si tu equipo usa Claude Code a través de un gateway, revisa también la autenticación y la configuración de la URL base. Una mala configuración de ANTHROPIC_BASE_URL o del ámbito de la clave puede ensuciar el diagnóstico del modelo; usa la guía de errores del token de autenticación de Claude Code cuando la autenticación también falle.

Paso 5: Decide si reintentar, hacer fallback o fallar de forma cerrada

No reintentes para siempre un error determinista de modelo ausente. Usa esta política:

Patrón de error	¿Reintentar?	¿Fallback?	Acción humana
ID de modelo con error tipográfico u obsoleto	No	Solo después de corregir la configuración	Actualizar el registro de modelos y volver a desplegar
Nuevo alias aún no enrutado	No hacer reintentos repetidos	Mantener el modelo verificado anterior	Abrir una tarea de habilitación de ruta/canary
El workspace no tiene acceso	No	Quizá, si existe un fallback aprobado	Corregir la clave, el workspace o la lista permitida
Error 400 de discrepancia en la forma de la solicitud	No	No hasta que la solicitud esté corregida	Parchear el cuerpo de la solicitud o los flags de función
529 por sobrecarga o caída transitoria del upstream	Sí, con backoff acotado	Sí, si la política de fallback lo permite	Monitorizar la salud de la ruta

Para el manejo de sobrecarga transitoria, usa otro runbook: Error 529 de API sobrecargada. Un fallo de versión de modelo suele ser determinista hasta que cambias la configuración.

Lista de verificación de revisión de rutas de Flatkey

Cuando Claude forma parte de un sistema multimodelo, un router te da un único lugar para revisar nombres de modelo, claves, listas permitidas, gasto y fallbacks. El posicionamiento de Flatkey es una clave, un saldo, una factura, endpoints oficiales de modelo y un libro mayor de uso compartido entre modelos y herramientas.

Usa esta lista de verificación antes de promover una nueva ruta 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 un diseño de rutas más amplio, lee proxy de API de Claude vs router multimodelo y la guía del catálogo de modelos de IA. Para compensaciones de coste y enrutamiento, combina este artículo con precios de la API de Claude y enrutamiento de fallback de API de LLM.

Lista de verificación de incidente copiable

Úsala en Slack, Linear, GitHub o en tu documento de incidente:

## Incidente de versión del modelo Claude no encontrada

- Cadena de modelo que falla:
- Superficie de API: Anthropic nativa / router / Bedrock / Vertex / otro
- URL base:
- Ruta de la solicitud:
- SDK o cliente:
- Código de estado:
- error.type:
- request-id:
- Primer despliegue con fallo:
- Alias oficial actual del modelo comprobado:
- ¿Pasa la solicitud mínima?
- ¿Está el modelo habilitado para este workspace/clave/subclave?
- ¿Es un error de función no admitida en lugar de modelo no encontrado?
- Modelo de rollback:
- Responsable:

Mantén la checklist aburrida. El objetivo es evitar que una versión de modelo Claude que falta se convierta en un incidente amplio en el que cada equipo cambie una configuración distinta.

Preguntas frecuentes

¿"Claude model version not found" es lo mismo que un 404?

A menudo, pero no siempre. Anthropic documenta 404 - not_found_error para recursos faltantes, mientras que los SDK y los gateways pueden reformular el mensaje. Conserva el código de estado en bruto y error.type antes de decidir.

¿Qué versiones de modelo Claude debo usar?

Usa los alias actuales del modelo desde la API o la superficie del proveedor que estés llamando. No copies una versión de modelo Claude de otro proveedor de nube, router o ejemplo de código antiguo sin comprobar el catálogo de ese endpoint.

¿Debo usar un alias o un snapshot con fecha?

Para la mayoría de los equipos de producto, un alias actual es más fácil de operar porque el proveedor controla el mapeo admitido. Si necesitas una reproducibilidad estricta, documenta la política exacta de snapshots, el plan de retirada y la ruta de reversión.

¿Puede Flatkey corregir Claude model version not found automáticamente?

Flatkey no puede hacer válido un ID de modelo ascendente inválido, pero sí puede reducir los lugares donde se esconden IDs incorrectos. Usa Flatkey para centralizar la revisión del catálogo de modelos, el enrutamiento con una sola clave, las listas permitidas de subclaves, los registros de uso y la política de fallback cuando Claude sea una ruta de modelo más entre varias.

¿Cuándo debo hacer fallback a otro modelo?

El fallback es apropiado después de clasificar el fallo. No hagas fallback por un typo, una URL base incorrecta o una clave no autorizada. Sí haz fallback cuando tu política diga que la ruta actual no está disponible y la siguiente ruta haya pasado las mismas comprobaciones de entrada, calidad y coste.

Comprobación final

Antes de cerrar un ticket de claude model version not found, confirma la corrección en tres lugares: configuración de origen, prueba mínima de API y registros de rutas de producción. Luego añade la versión de modelo Claude que funciona a tu registro de modelos para que el próximo despliegue no reintroduzca la misma cadena obsoleta.

Si ya estás enrutando varios modelos, prueba el mismo cambio a través de Flatkey para que tu ledger de solicitudes, la política de fallback y las listas permitidas de modelos estén alineados antes de que el tráfico de producción se mueva.

Referencias oficiales

• Resumen de los modelos Claude de Anthropic
• Referencia de la API Messages de Anthropic
• Errores de la API de Anthropic
• Página principal y posicionamiento del producto Flatkey