3. Proyecto base
Interpreta los errores de la conexión
Distingue credenciales, límites, modelo y red antes de intentar otra llamada.
Qué aprenderás
- Clasificar errores HTTP sin asumir que todos son de credenciales.
- Reconocer que un fallo de red puede no tener statusCode.
- Mantener visible el fallo y elegir una corrección concreta.
Índice de esta lección
Paso 1
Lee la señal que realmente tienes
La base incluye getMessageFromModelFailSafe con mensajes para credenciales, límites, modelo y red. Un error HTTP y un fallo de conexión son señales distintas.
401 o 403 orientan a autenticación o permisos; 429 puede indicar cuota o límite de solicitudes; 404 orienta al recurso o modelo; los 5xx indican errores de servidor. El mensaje concreto del proveedor puede añadir contexto.
401 / 403 → credencial o permisos429 → cuota o límite de solicitudes404 → recurso, modelo o URL5xx → error del servidorSin HTTP → investigar red y configuraciónQué deberías observar
No tratas todos los fallos como si fueran la misma causa ni das un diagnóstico definitivo solo por el número.
Paso 2
Maneja la llamada sin ocultar el fallo
Añade esta variante al archivo de acciones. Evita repetir los imports si ya los tienes. APICallError.isInstance permite leer statusCode cuando el error pertenece a esa clase.
El catch recibe unknown. Conservamos el fallo con process.exitCode = 1 para que terminar la función no se interprete como una ejecución satisfactoria. El ejemplo muestra mensajes acotados sin volcar credenciales ni respuestas completas del proveedor.
import { APICallError, generateText } from 'ai';import { model } from '../helpers/selected-model.js'; export async function getMessageFromModelFailSafe() { try { const { text } = await generateText({ model, prompt: 'Responde solamente con: "OK, todo listo!"', }); console.log('Respuesta:', text.trim()); } catch (error: unknown) { if (APICallError.isInstance(error)) { const status = error.statusCode; if (status === 401 || status === 403) { console.error('Revisa la credencial y sus permisos.'); } else if (status === 429) { console.error('Revisa la cuota o el límite de solicitudes.'); } else if (status === 404) { console.error('Revisa el modelo y la URL del proveedor.'); } else if (status !== undefined && status >= 500) { console.error('El proveedor respondió con un error de servidor.'); } else { console.error('La petición falló. Revisa su configuración.'); } } else { console.error('No se completó la llamada. Revisa red y configuración.'); } process.exitCode = 1; }}Qué deberías observar
Los errores reconocidos imprimen una orientación. Ante un fallo, el proceso termina con un código de salida distinto de cero.
Paso 3
Distingue red de respuesta HTTP
Si no hay una respuesta HTTP, puede haber un problema de DNS, un servicio local detenido o una dirección equivocada. En la base de estudio se revisan códigos como ENOTFOUND y ECONNREFUSED.
Un código puede estar dentro de cause, pero no todos los errores comparten esa estructura. No fuerces un statusCode ni conviertas cualquier error a any para asumirlo. Empieza por confirmar dirección, servicio y conectividad.
ENOTFOUND → revisar dominio y conectividadECONNREFUSED → revisar dirección y servicio escuchandoSi se usa un proveedor local → comprobar que esté iniciadoSi no hay código conocido → conservar el fallo y revisar configuraciónQué deberías observar
Puedes escoger el siguiente chequeo sin fingir que el error pertenece al proveedor HTTP.
Paso 4
Ejecuta la variante de diagnóstico
Reemplaza main.ts por esta variante. Ejecuta npm run build y después npm run dev.
Para practicar sin realizar nuevas llamadas puedes usar el mapa anterior y clasificar casos escritos. Cuando haya un error real, corrige su causa antes de repetir; esta base aún no implementa circuit breaker ni una política propia de reintentos.
import { getMessageFromModelFailSafe } from './actions/get-message-model.js'; await getMessageFromModelFailSafe();Qué deberías observar
La práctica imprime la respuesta o informa el fallo. Puedes explicar qué revisarías según la señal observada.
Ahora te toca
Prueba la idea por tu cuenta
Clasifica estos casos y propón una comprobación: 403, 429 y ECONNREFUSED. Explica por qué no resolverías todos regenerando la API key.
Necesito una pista
Permisos, límites y disponibilidad de un servicio pertenecen a problemas diferentes.
Comparar con una solución
Para 403 revisa permisos y credencial. Para 429 consulta cuota y límites antes de otra llamada. Para ECONNREFUSED revisa dirección y servicio. Renovar una llave no inicia un servicio ni cambia automáticamente la cuota.
Antes de seguir
Comprueba lo que aprendiste
No es una nota. Es una pausa para comprobar que la idea quedó clara.
¿Terminaste la práctica?
Haz el ejercicio y comprueba tus respuestas antes de marcar la lección como completada.