Erros Comuns
Erros HTTP
401 Unauthorized
| Sintoma | Os pedidos à API devolvem 401, ou a interface redireciona inesperadamente para a página de login |
| Causa | A sua sessão OAuth2 expirou ou o token é inválido |
| Solução | Termine sessão e volte a iniciar sessão. Se o problema persistir após o re-login, limpe os cookies do navegador e o localStorage para o domínio OpSee e inicie sessão novamente. Consulte Problemas de Login para mais detalhes. |
403 Forbidden
| Sintoma | A página carrega mas os dados não aparecem, ou uma ação devolve um erro 403 |
| Causa | A sua conta Keycloak não tem o papel necessário para este recurso |
| Solução | Contacte o seu administrador Keycloak para verificar as atribuições de papéis. Verifique os seus papéis atuais em Perfil → Papéis e Permissões. Papéis comummente necessários: menu:production, equipment:view, menu:admin. |
404 Not Found
| Sintoma | Uma página ou endpoint da API devolve 404 |
| Causa | O URL não existe (erro de digitação, marcador desatualizado) ou o módulo não está implementado nesta instância |
| Solução | Navegue até à página a partir do menu principal. Se o próprio item de menu estiver em falta, a funcionalidade poderá não estar ativada na sua instalação, contacte o seu administrador. |
500 Internal Server Error
| Sintoma | Uma ação falha com uma mensagem genérica de erro do servidor |
| Causa | Uma exceção não tratada no backend da API |
| Solução | Verifique os logs do contentor backend (docker logs opsee-fastapi). Se o erro for reproduzível, anote a ação exata que o desencadeia e reporte ao seu administrador com o timestamp para que possa correlacionar a entrada do log. |
502 Bad Gateway / 503 Service Unavailable
| Sintoma | A aplicação inteira mostra uma página de erro 502 ou 503 |
| Causa | O serviço backend ou uma das suas dependências (base de dados, Keycloak) está em baixo ou ainda não foi iniciado |
| Solução | Execute docker ps no servidor para verificar quais contentores estão a correr. Reinicie contentores parados com docker compose up -d. Se a base de dados for o problema, verifique se há esgotamento de espaço em disco ou erros de limite de ligações. |
Erros de Rede
"Cannot connect" / Erro de Rede
| Sintoma | As chamadas à API falham com um erro de rede na consola do navegador; nenhum código de estado HTTP é devolvido |
| Causa | O contentor backend do OpSee não está a correr, ou o reverse proxy NGINX não consegue alcançá-lo |
| Solução | Verifique se os contentores Docker estão ativos: docker ps. Se o contentor backend tiver saído, inspecione os seus logs com docker logs opsee-fastapi. Reinicie com docker compose up -d. |
Erros de Validação de Formulário
Campo obrigatório / formato inválido
| Sintoma | Um formulário recusa-se a ser submetido e destaca campos a vermelho |
| Causa | Um campo obrigatório está vazio, um valor não corresponde ao formato esperado (ex.: um campo de data contém texto), ou a entrada excede o comprimento máximo |
| Solução | Preencha todos os campos destacados. Preste atenção às dicas de formato apresentadas por baixo de cada campo. |
Entrada duplicada
| Sintoma | O formulário é submetido mas devolve um erro como "já existe" ou "chave duplicada" |
| Causa | Um registo com o mesmo identificador único (nome, código, etc.) já existe na base de dados |
| Solução | Use um valor diferente para o campo único, ou edite o registo existente em vez de criar um novo. |