Errores comunes
Errores HTTP
401 No autorizado
| Síntoma | Las solicitudes a la API devuelven 401 o la interfaz redirige a la página de inicio de sesión inesperadamente |
| Causa | Su sesión OAuth2 ha expirado o el token no es válido |
| Solución | Cierre sesión y vuelva a iniciarla. Si el problema persiste tras volver a iniciar sesión, borre las cookies del navegador y el localStorage del dominio de OpSee, y luego inicie sesión de nuevo. Consulte Problemas de inicio de sesión para más detalles. |
403 Prohibido
| Síntoma | La página se carga pero los datos no aparecen, o una acción devuelve un error 403 |
| Causa | Su cuenta de Keycloak no tiene el rol necesario para este recurso |
| Solución | Contacte con su administrador de Keycloak para verificar las asignaciones de roles. Compruebe sus roles actuales en Perfil → Roles y permisos. Roles habituales necesarios: menu:production, equipment:view, menu:admin. |
404 No encontrado
| Síntoma | Una página o un endpoint de API devuelve 404 |
| Causa | La URL no existe (error tipográfico, marcador desactualizado) o el módulo no está desplegado en esta instancia |
| Solución | Navegue a la página desde el menú principal. Si el propio elemento del menú no aparece, es posible que la funcionalidad no esté habilitada en su despliegue, contacte con su administrador. |
500 Error interno del servidor
| Síntoma | Una acción falla con un mensaje genérico de error del servidor |
| Causa | Una excepción no controlada en la API del backend |
| Solución | Compruebe los logs del contenedor del backend (docker logs opsee-fastapi). Si el error es reproducible, anote la acción exacta que lo desencadena y comuníquelo a su administrador con la marca de tiempo, para que pueda correlacionarlo con la entrada del log. |
502 Pasarela incorrecta / 503 Servicio no disponible
| Síntoma | Toda la aplicación muestra una página de error 502 o 503 |
| Causa | El servicio del backend o una de sus dependencias (base de datos, Keycloak) está caído o no se ha iniciado todavía |
| Solución | Ejecute docker ps en el servidor para comprobar qué contenedores están en ejecución. Reinicie los contenedores detenidos con docker compose up -d. Si el problema es la base de datos, compruebe si hay falta de espacio en disco o errores de límite de conexiones. |
Errores de red
"No se puede conectar" / Error de red
| Síntoma | Las llamadas a la API fallan con un error de red en la consola del navegador; no se devuelve ningún código de estado HTTP |
| Causa | El contenedor del backend de OpSee no está en ejecución, o el proxy inverso NGINX no puede llegar a él |
| Solución | Verifique que los contenedores de Docker están activos: docker ps. Si el contenedor del backend ha salido, examine sus logs con docker logs opsee-fastapi. Reinicie con docker compose up -d. |
Errores de validación de formularios
Campo obligatorio / formato no válido
| Síntoma | Un formulario no se envía y resalta los campos en rojo |
| Causa | Un campo obligatorio está vacío, un valor no coincide con el formato esperado (por ejemplo, un campo de fecha contiene texto), o la entrada supera la longitud máxima |
| Solución | Rellene todos los campos resaltados. Preste atención a las pistas de formato que aparecen debajo de cada campo. |
Entrada duplicada
| Síntoma | El formulario se envía pero devuelve un error como "ya existe" o "clave duplicada" |
| Causa | Ya existe un registro con el mismo identificador único (nombre, código, etc.) en la base de datos |
| Solución | Use un valor distinto para el campo único, o edite el registro existente en lugar de crear uno nuevo. |