Errores y fiabilidad

Model Not Found: cómo diagnosticar y corregir el error de API

Rastree un error model not found mediante endpoint, protocolo, API Key, Model ID, alias, overrides, estado y request ID.

BT

BetterToken

Equipo editorial
6 min de lectura

El error model not found significa que el servidor no pudo resolver la Model ID especificada en el contexto del endpoint y la API Key actuales. Puede deberse a errata, alias antiguo, protocolo incorrecto, falta de acceso u override de configuración. Anote estado y request ID, y revise la cadena desde Base URL hasta clave y modelo. Elegir nombres al azar solo oculta el error original.

Qué guardar antes de cambiar la configuración

Primero registre una ficha breve de diagnóstico:

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_...

La API Key, el prompt completo y la respuesta no deben estar en la ficha. Si el error apareció en IDE o herramienta Agent, anote por separado el archivo de configuración y si hay variables de entorno. Así podrá saber qué valor llegó realmente al servidor.

¿Quiere repetir el diagnóstico con el catálogo actual? Puede crear su propia cuenta BetterToken y API Key, comprobar endpoint y Model ID con la referencia API, y ejecutar una solicitud mínima. En BetterToken deben coincidir tipo de endpoint, Base URL, grupo de Key y Model ID actual. Tome el nombre actual de documentación o de la página de modelos y precios, y compruebe el resultado en Dashboard.

Paso 1: comprobar Base URL y ruta

Mire la URL final de la solicitud, no solo la línea de ajustes. El SDK puede añadir por sí mismo /v1, /models, /chat/completions, /responses o /messages.

Errores frecuentes:

  • Base URL ya contiene la ruta de recurso y SDK la añade una segunda vez;
  • falta /v1 o está duplicado;
  • el cliente OpenAI envía a dirección Anthropic-compatible;
  • una variable de entorno sobrescribe Base URL del config;
  • la aplicación usa otro perfil o workspace.

Para BetterToken OpenAI-compatible, las herramientas usan Base URL con /v1; Anthropic SDK y Claude Code usan dirección sin /v1, y la ruta Messages completa se genera aparte. Antes de corregir, consulte la página vigente de la herramienta concreta.

Paso 2: comprobar qué API Key se usa realmente

La misma interfaz puede almacenar varias credenciales. A veces un error de modelo oculta que la Key seleccionada no tiene acceso.

Compruebe:

  1. credential o variable de entorno desde la que el cliente lee la clave;
  2. ausencia de espacios o saltos de línea extra;
  3. correspondencia de la Key con protocolo y grupo de modelos;
  4. si config del proyecto sustituye el ajuste global;
  5. si la Key expiró o fue revocada.

No muestre la clave con echo, log de depuración ni captura. Para comparar credenciales basta un nombre de perfil seguro o los últimos caracteres de fingerprint si la interfaz los muestra.

Paso 3: obtener la Model ID actual

Un endpoint OpenAI-compatible suele tener lista de modelos. Una solicitud segura de diagnóstico tiene este aspecto:

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

El comando usa variables de entorno y no contiene la clave real. Solo es apropiado cuando la documentación del endpoint confirma /models.

Para otro protocolo o cliente, use el directorio oficial del provider. Copie el campo id sin cambiar mayúsculas, espacios ni sufijos. El nombre comercial y la API Model ID pueden diferir.

Si la lista abre pero falta el modelo deseado, compruebe Key y catálogo. Si /models devuelve error, arregle primero endpoint o autorización.

Paso 4: localizar alias y ajuste heredado

Model ID puede venir de varias fuentes:

  • config del proyecto;
  • config global del cliente;
  • variable de entorno;
  • perfil de UI;
  • flag de línea de comandos;
  • sesión guardada;
  • gateway de routing o mapping de modelo.

Buscar en el repositorio ayuda a encontrar el valor antiguo:

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

La búsqueda también puede encontrar archivos de configuración con secretos. No publique la salida completa. Corrija solo la fuente que lee el cliente.

Las herramientas AI suelen priorizar “config del proyecto sobre config global”. Tras cambiar, reinicie el cliente o abra sesión nueva si guarda en caché ajustes del provider.

Paso 5: separar error de modelo de error de acceso

Los códigos HTTP de APIs compatibles no tienen que coincidir; revise también el cuerpo de error.

  • 401: compruebe primero credential y formato de autorización.
  • 403: el modelo puede existir, pero la Key actual no tiene acceso.
  • 404: posible error de ruta, endpoint o Model ID.
  • 400: el servidor puede haber rechazado model u otro parámetro.
  • 429 / 5xx: normalmente es otra categoría; no cambie Model ID sin señal adicional.

La frase model not found de UI puede ser paráfrasis del cliente. Encuentre estado HTTP, código provider y request ID originales.

Retest mínimo

Después de corregir, envíe una solicitud corta sin streaming ni herramientas. Para Chat Completions OpenAI-compatible, el esquema puede 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 y endpoint deben coincidir con documentación del provider. No traslade el ejemplo a Anthropic Messages sin adaptarlo.

Una comprobación correcta tiene cuatro coincidencias:

  • estado HTTP de éxito;
  • respuesta indica Model ID esperada o su versión documentada;
  • solicitud aparece en Dashboard;
  • hora, estado y uso coinciden con la prueba.

Si la consulta corta funciona y el IDE aún muestra model not found, la configuración del servidor ya se corrigió. Busque override o caché dentro del cliente.

Lista de control breve

  • Estado, código provider y request ID guardados.
  • URL final comprobada sin /v1 ni ruta de recurso duplicados.
  • Cliente usa credential esperada.
  • Model ID tomada del catálogo actual.
  • Overrides de proyecto, globales y de entorno comprobados.
  • Solicitud mínima sin herramientas ni stream ejecutada.
  • Solicitud vinculada a Dashboard.

En BetterToken consulte la referencia API y el catálogo de modelos actual antes de sustituir Model ID. Es más seguro y rápido que buscar nombres parecidos.

Preguntas frecuentes

¿Por qué el modelo es visible en el sitio, pero la API devuelve model not found?

Puede haber otro protocolo, grupo de Key, región de catálogo, sesión antigua o diferencia entre nombre comercial y API ID. Compruebe la lista de modelos específicamente para el credential actual.

¿Ayuda repetir la solicitud?

No si hay errata o endpoint incorrecto. Primero corrija configuración. Reintentar solo es adecuado para error temporal cuando estado y código provider lo confirman.

¿Se puede guardar para siempre la lista de modelos en config?

Guarde la ID elegida como ajuste gestionado y compárela periódicamente con catálogo actual. Disponibilidad y alias pueden cambiar.

¿Por qué curl funciona pero la aplicación no?

La aplicación puede leer otra Base URL, otro credential u otra Model ID. Compare solicitud final y compruebe override de proyecto, variables de entorno y perfil guardado.

Fuentes

¿Quieres optimizar tu flujo de trabajo con LLM?

Conecta modelos mediante una API, gestiona claves y controla el gasto en IA.