Códigos de error comunes

Cuando te encuentres con un código de estado, identifica primero el tipo de problema y luego revísalo según la prioridad

Mucha gente, en cuanto ve un error, empieza a sospechar que hay un problema con la plataforma, pero en realidad, la mayoría de los errores en la integración con MoleAPI pueden localizarse rápidamente mediante código de estado + elementos de configuración.

Enfoque de diagnóstico más recomendado

No descartes toda la configuración desde el principio. Se recomienda comprobarlo en este orden:

Primero, revisa cuál es el código de estado
Luego, determina si se trata de un problema de identidad, permisos, dirección o contenido de la solicitud
Por último, vuelve a la consola para revisar la configuración correspondiente

Consulta rápida de códigos de error

Código de estado	Significado habitual	Qué deberías comprobar primero
400	Error en los parámetros de la solicitud	Estructura JSON, tipo de campos, si el modelo admite ese parámetro
401	Error de autenticación	Si la API Key es correcta, si tiene espacios de más, si ha caducado
403	Permisos insuficientes	Permisos del modelo, grupo, lista blanca de IP, límite de la Key
404	Error de dirección o routing	Si el Base URL es correcto, si falta `/v1`, si la ruta está mal escrita
429	Rate limit o problema de quota	Si se ha alcanzado la frecuencia de solicitud, concurrencia, saldo, quota o límite
500	Excepción del servidor	Reintenta primero y conserva la información de la solicitud; si persiste, contacta con soporte

Comprender cada código de estado

400: el problema está en la propia solicitud

Este tipo de error suele indicar que:

La estructura de tu solicitud no es correcta
El tipo de algún campo no es correcto
Estás enviando al modelo un parámetro que no admite

Si hace poco cambiaste de modelo, de SDK, o copiaste el código de ejemplo de otra persona, este es el primer punto que deberías revisar.

401: hay un problema con la API Key

Comprueba primero:

Si has introducido un sk-... creado en la consola de MoleAPI
Si hay espacios al principio o al final
Si la copia está incompleta
Si has pegado por error una Key de otra plataforma

403: puedes acceder a la interfaz, pero no tienes permisos para hacerlo

Este error es más habitual cuando:

La Key actual no tiene permisos para ese modelo
El grupo actual no admite ese modelo
Se ha configurado una lista blanca de IP, pero la IP de origen no coincide
Se ha activado la quota o alguna restricción de la propia Key

404: la dirección es incorrecta

Este es uno de los problemas más comunes entre principiantes.

Comprueba primero:

Si el Base URL está configurado como https://api.moleapi.com/v1
Si sigues enviando solicitudes a api.openai.com
Si has puesto por error la ruta completa de la interfaz como Base URL

429: estás limitado o ya no tienes quota suficiente

Cuando veas un 429, no pienses solo en “estoy enviando solicitudes demasiado rápido”; revisa también al mismo tiempo:

Si el saldo es insuficiente
Si la Key tiene algún límite
Si la concurrencia es demasiado alta
Si estás enviando demasiadas solicitudes en muy poco tiempo

500: excepción del servidor

Si ocurre de forma ocasional, puedes reintentar primero; si se reproduce de forma estable, se recomienda conservar:

Hora de la solicitud
Nombre del modelo
Parámetros de la solicitud
Request ID (si el cliente lo proporciona)

Así, la revisión posterior será mucho más rápida.

Un orden de revisión muy práctico

Cuando no sepas por dónde empezar, este orden te ahorrará tiempo:

Revisa el código de estado
Revisa el Base URL
Revisa la API Key
Revisa el nombre del modelo
Revisa grupo / permisos / límite
Revisa saldo y logs

Regla práctica

Con un 404, casi siempre conviene revisar primero la dirección; con un 401, casi siempre la Key; con un 403, casi siempre los permisos; con un 429, no solo la frecuencia, también el saldo y el límite.