Troubleshooting

Este capítulo descreve os principais problemas que podem impedir a API de iniciar corretamente como serviço Windows, além dos passos de diagnóstico recomendados para equipes técnicas e clientes.

IDProblemaSintoma / LogsCausa provávelComo diagnosticar (comandos)Solução / Ação recomendada
1Porta já está em usoServiço inicia e para.

No Event Viewer aparece erro semelhante a:
SocketException (10013)
ou
Only one usage of each socket address... 		A porta configurada para a API já está sendo utilizada por outro processo.

  • Abrir o Prompt de Comando como Administrador.

  • Executar:

netstat -ano | findstr :PORTA

Como interpretar

  • Se aparecer alguma linha retornando LISTENING, anote o PID (no exemplo acima o PID é o 30188).

  • Identifique o processo pelo PID:

tasklist /FI "PID eq 1234"

  • Alterar a porta no arquivo appsettings.json da API.

  • Ou parar o processo que está ocupando a porta.

  • Reiniciar o serviço após a correção.


2Falta de permissão ao bind (conta do serviço)“Access is denied” ao iniciar; erro 10013Conta do serviço (LocalService/NetworkService/conta custom) não tem privilégios para executar ações necessáriasVerificar conta do serviço no Services.msc; testar executando o exe manualmente com a mesma conta (se possível)Executar serviço com conta com permissão adequada (LocalSystem ou conta custom com privilégios). Ajustar permissões na pasta/registries se necessário.
3Firewall ou antivírus bloqueando o tráfegoAPI responde em localhost mas não externamente; timeout ao acessar IP:PORTARegras de firewall/antivírus bloqueando porta

Teste local: curl http://localhost:PORTA/health

Teste remoto: curl http://IP_DO_SERVIDOR:PORTA/health


Exemplo de retorno com sucesso:

Exemplo de retorno com falha:

Consultar time de infra para exceções ou ajustar a política conforme processo da empresa.

-Liberar porta;

-Ajustar regras do antivírus, se aplicável.


4Aplicação não inicia — Porta reservada (<1024) sem ADMIN

Portas como 80 e 443 exigem privilégios elevados.

Sintoma

API falha ao iniciar e o Event Viewer mostra erro de acesso negado.

Portas privilegiadas exigem privilégios elevados

Verificar porta configurada em appsettings.json

  • Rodar o serviço com conta privilegiada (administrador/LocalSystem).

  • Ou usar portas acima de 1024 (recomendado).


5API depende de configurações externas ausentes (appsettings.json)No Event Viewer aparece erros de configuração, como:
Could not find key 'ConnectionStrings:DefaultConnection'

Arquivo ausente, caminho errado ou JSON inválido

  • Verificar se o arquivo appsettings.json está presente e com as configurações corretas.

  • Garantir que o serviço possua permissões de leitura na pasta da API.

Corrigir valores; garantir que o serviço tenha permissão de leitura no arquivo e que variáveis de ambiente estejam definidas para o serviço, se usadas.

Se necessário, utilize o instalador da API Linx ERP para desinstalar o serviço e instale novamente.

6Serviço sem permissões de leitura na pasta da API

O Event Viewer exibe erros como:

UnauthorizedAccessException: Access to the path is denied.

Conta do serviço não tem permissões NTFS

Verificar se a conta do serviço tem acesso à pasta:

  • Clique direito → Propriedades

  • Aba Segurança

  • Garantir permissão Ler/Executar

Conceder Read & Execute + List Folder Contents à conta do serviço.
7GPOs / políticas de segurança do servidorBloqueios estranhos / regras aplicadas automaticamentePolítica corporativa bloqueando portas/serviçosConferir GPOs aplicados ao servidor (gpresult /R) e logs de segurançaConsultar time de infra para exceções ou ajustar a política conforme processo da empresa.



  • Sem rótulos