Tratamento e recuperação de erros

Entender como interpretar, responder e relatar erros ajuda você a manter sessões de desenvolvimento produtivas com Verdent for VS Code.

O que você vai aprender

Tipos comuns de erro e suas causas
Como interpretar mensagens de erro de forma eficaz
Passos sistemáticos de solução de problemas
Quando esperar e quando agir
Como relatar problemas à equipe do Verdent

A documentação completa de erros ainda está em desenvolvimento. As informações abaixo cobrem as categorias de erro mais frequentes. Para cenários de erro específicos, entre em contato com support@verdent.ai ou acesse a comunidade no Discord.

Erros de servidor sobrecarregado

Ocorrem durante períodos de alto tráfego
Restrições temporárias de capacidade
Ação: Aguarde de 5 a 10 minutos e tente novamente

Erros internos de servidor

Problemas de processamento no backend
Interrupções temporárias de serviço
Ação: Aguarde e tente novamente; geralmente se resolve automaticamente

503 Service Unavailable

Nenhum servidor upstream saudável
Problemas temporários de infraestrutura
Ação: Aguarde a recuperação do serviço

Erros de limite de taxa

Cotas de requisição excedidas
Proteções de throttling do API
Ação: Aguarde o reset do limite de taxa, reduza a frequência das requisições

Credenciais inválidas ou expiradas
Problemas de timeout de sessão
Ação: Reautentique-se pelo User Center, verifique se a assinatura está ativa

Problemas de conectividade de rede
Firewall ou VPN bloqueando conexões
Restrições de rede corporativa
Ação: Verifique a conexão de rede, tente uma rede diferente

Configurações ou preferências inválidas
Arquivos de configuração corrompidos
Ação: Revise alterações recentes de configuração, verifique a configuração

Permissões insuficientes no sistema de arquivos
Restrições de acesso ao espaço de trabalho
Ação: Verifique as permissões de arquivo/pasta, confirme o acesso ao espaço de trabalho

Interpretando mensagens de erro

O guia detalhado de interpretação de mensagens de erro está em desenvolvimento. Para mensagens de erro específicas que você encontrar, use o botão de Feedback ou a comunidade no Discord para obter ajuda.

Os erros do lado do servidor são temporários e geralmente se resolvem com o tempo. Nenhuma ação é necessária além de tentar novamente após alguns minutos.

Procure por estas palavras-chave:

"Overloaded" ou "at capacity"
"Internal server error" ou "backend processing"
"503 Service Unavailable" ou "no healthy upstream"
"Rate limit" ou "quota"

O que fazer:

Aguarde de 5 a 10 minutos antes de tentar novamente
Continue o trabalho de desenvolvimento local
Revise as alterações de código feitas até agora
Faça commit do trabalho atual no Git

Regra geral: Se a mensagem de erro mencionar status do servidor, capacidade ou limites de taxa, é algo temporário. São problemas de infraestrutura que se resolvem automaticamente.

Erros temporários de servidor (502, 503, 504) geralmente se resolvem em minutos. Aguarde de 2 a 3 minutos antes de tentar novamente.

Quando escalar:

O erro persiste por mais de 15 minutos
Verifique o Discord em busca de relatos de interrupção
Procure atualizações na página de status

Os erros do lado do cliente exigem ação da sua parte. Eles não se resolvem com o tempo.

Procure por estes indicadores:

Mensagens relacionadas a autenticação ou credenciais
Erros de configuração ou ajustes
Erros de permissão de arquivo
Falhas de conexão de rede

O que fazer:

Erros de autenticação: Reautentique-se pelo User Center, verifique se a assinatura está ativa
Erros de configuração: Revise alterações recentes de configuração, verifique os arquivos de configuração
Erros de permissão: Verifique as permissões de arquivo/pasta, confirme o acesso ao espaço de trabalho
Erros de rede: Teste a conexão com a internet, tente uma rede diferente, verifique VPN/firewall

Regra geral: Se o erro mencionar autenticação, configuração, permissões ou ajustes locais, você precisa tomar uma ação corretiva.

Passos de solução de problemas:

Leia a mensagem de erro completa em busca de orientações específicas
Identifique qual componente reportou o erro (autenticação, configuração, permissões, rede)
Tome uma ação direcionada com base no tipo de erro
Verifique a correção tentando novamente a operação original

Lendo o contexto do erro

Quando ocorrer um erro:

Leia a mensagem de erro completa - Não pule detalhes
Anote os códigos de erro - Códigos específicos ajudam a diagnosticar os problemas
Identifique o componente - Qual sistema reportou o erro (servidor, API, local)
Verifique o momento - Aconteceu imediatamente ou após um atraso?

Solução de problemas sistemática

Siga estes passos progressivos quando o Verdent se comportar de forma inesperada, começando pelas ações menos disruptivas.

Resposta inicial

Aguarde e observe

Verifique se o comportamento é consistente ou intermitente. Anote qual ação disparou o comportamento inesperado. Não presuma imediatamente que algo está quebrado - muitos problemas são temporários.

Reinicialização básica

Reinicie o Verdent for VS Code (feche e reabra o VS Code). Muitas vezes resolve estados travados ou problemas de desempenho. Este é o primeiro e mais simples passo de solução de problemas.

Solução de problemas progressiva

Se a reinicialização básica não resolver o problema:

Siga os passos sistemáticos de solução de problemas em ordem; pular passos muitas vezes significa não identificar a causa raiz.

Verifique a conexão de rede

Teste a conexão com a internet acessando outros sites. Experimente uma rede diferente (hotspot do celular) para descartar problemas de firewall/VPN. Verifique se a rede corporativa está bloqueando conexões.

Verifique a configuração

Confirme se você ainda está autenticado. Verifique se a assinatura está ativa no User Center. Revise alterações recentes de configuração que possam afetar o comportamento.

Busque ajuda

Verifique a comunidade no Discord em busca de relatos semelhantes: https://discord.com/invite/NGjXEZcbJq. Use o botão de Feedback para relatar o problema. Inclua a descrição do comportamento inesperado e os passos para reproduzi-lo.

O que NÃO fazer

Evite estas ações para problemas temporários:

Não reinstale o Verdent imediatamente
Não limpe o cache do VS Code nem os dados do aplicativo
Não modifique configurações do sistema para problemas temporários
Não reinicie o computador, a menos que outros aplicativos também sejam afetados

No Manual Accept Mode, nunca aprove operações destrutivas (rm, DROP, DELETE) sem revisar cuidadosamente o comando exato.

Por quê? Essas ações consomem tempo e raramente corrigem problemas. A maioria dos problemas se resolve com uma simples reinicialização ou aguardando o término de problemas temporários do servidor.

Quando esperar e quando agir

Entender se deve esperar ou agir evita esforço desperdiçado na solução de problemas.

Esses erros se resolvem automaticamente - nenhuma ação é necessária além de esperar e tentar novamente.

Erros de sobrecarga ou capacidade do servidor:

Mensagens "Overloaded" ou "at capacity"
Períodos de alto tráfego
Interrupções temporárias de serviço

Limite de taxa:

Mensagens "Rate limit" ou "quota exceeded"
Requisições demais em pouco tempo
Proteção de throttling do API

Problemas intermitentes de conexão:

Requisições que falham ocasionalmente e funcionam ao tentar novamente
Instabilidades de rede
Quedas breves de conectividade

O que fazer enquanto espera:

Continue o trabalho de desenvolvimento local
Revise as alterações de código feitas até agora
Planeje os próximos passos ou tarefas pendentes
Faça commit do trabalho atual no Git

Quanto tempo esperar:

Espera padrão: 5 a 10 minutos
Se ainda falhar após 10 minutos, passe para a solução de problemas
Verifique o Discord em busca de relatos de problemas generalizados

Esses erros não se resolvem com o tempo - você deve tomar uma ação corretiva.

Falhas de autenticação:

Sessão expirada → Reautentique-se pelo User Center
Credenciais inválidas → Verifique se a assinatura está ativa
Necessidade de reautenticar → Verifique o User Center

Erros persistentes (mais de 10 minutos):

Mesmo erro repetidamente após várias tentativas → Inicie a solução de problemas
Padrão consistente de falha → Verifique a configuração
O erro persiste mesmo após reinicializações → Verifique o ambiente

Problemas de configuração:

Configurações alteradas recentemente → Revise e reverta as alterações
Nova configuração ou instalação → Verifique os arquivos de configuração
Mudança de ambiente de rede → Teste a conectividade

Erros de permissão:

Acesso negado ao sistema de arquivos → Verifique as permissões de arquivo/pasta
Restrições do espaço de trabalho → Confirme o acesso ao espaço de trabalho
Permissões de pasta → Conceda as permissões necessárias

Problemas de rede:

Incapacidade total de conexão → Teste a conexão com a internet
VPN ou firewall bloqueando → Tente uma rede diferente
Restrições de rede corporativa → Contate o suporte de TI

Regra de decisão:

Erros de servidor/taxa → Espere
Autenticação/configuração/permissão/rede → Aja imediatamente
Não tem certeza? → Espere de 5 a 10 minutos primeiro e, se persistir, aja

Fornecendo contexto do erro

Ao buscar ajuda ou relatar problemas, inclua um contexto abrangente para um diagnóstico mais rápido.

Informações essenciais

Detalhes do erro:

Texto exato da mensagem de erro (copie e cole, não parafraseie)
Código de erro, se fornecido
Carimbo de data/hora de quando o erro ocorreu
Frequência (única vez, intermitente, consistente)

Ambiente:

Versão do Verdent for VS Code
Versão do VS Code
Sistema operacional e versão
Ambiente de rede (casa, empresa, VPN)

Passos para reproduzir:

O que você estava tentando fazer
Prompts ou comandos exatos usados
Arquivos ou contexto envolvidos
Ações tomadas antes do erro

Contexto:

Qual modo de execução você estava usando
Tamanho e complexidade do espaço de trabalho
Alterações recentes de configuração
Operações semelhantes anteriores bem-sucedidas

Exemplo de relatório de erro

Bom formato de relatório de erro:

Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally

O que torna isso eficaz

Texto exato da mensagem de erro
Detalhes completos do ambiente
Passos claros para reproduzir
Comparação com cenários que funcionam
Contexto adicional sobre padrões

Relatando problemas

Localização: Barra superior do painel do Verdent

O que faz:

Abre uma janela sobreposta para enviar problemas e sugestões
Canal direto com a equipe do Verdent
Ideal para relatórios de bugs e solicitações de recursos

Quando usar:

Bugs confirmados com passos claros de reprodução
Solicitações de recursos com casos de uso específicos
Quando é necessária comunicação direta com a equipe
Problemas não urgentes que exigem investigação

O que incluir:

Descrição clara do problema
Mensagens de erro (texto exato)
Passos para reproduzir
Comportamento esperado versus comportamento real
Versão e plataforma do Verdent
Quando o problema começou

Link: https://discord.com/invite/NGjXEZcbJq

O que oferece:

Comunidade ativa de usuários do Verdent e membros da equipe
Assistência de solução de problemas em tempo real
Compartilhamento de problemas com capturas de tela
Ajuda de usuários experientes
Discussão da comunidade e soluções alternativas

Quando usar:

Problemas urgentes que exigem discussão imediata
Solução de problemas complexa que exige idas e vindas
Contribuição da comunidade sobre boas práticas
Perguntas rápidas antes de abrir relatórios formais
Compartilhamento de soluções alternativas com a comunidade

Tipo de problema	Usar botão de Feedback	Usar Discord
Bug confirmado com passos de reprodução	✓
Solicitação de recurso	✓
Solução de problemas urgente		✓
Problema complexo que precisa de discussão		✓
Pergunta rápida		✓
Querer a contribuição da comunidade		✓
Relatório formal de bug	✓
Ajuda geral		✓

O que NÃO relatar:

Erros temporários de servidor (menos de 10 minutos)
Períodos de alto tráfego
Problemas já documentados
Comportamento esperado

Em vez disso: Aguarde os problemas temporários, verifique o Discord em busca de relatos recentes, revise a documentação.

Boas práticas de prevenção

Práticas proativas reduzem a frequência de erros e melhoram a recuperação quando eles ocorrem.

Use linguagem específica nos prompts e inclua o contexto de arquivo relevante para evitar muitos erros comuns antes que aconteçam.

Antes de começar o trabalho

1. Verifique a configuração

Verifique o status de autenticação no User Center
Confirme se a assinatura está ativa
Garanta uma conexão de rede estável
Revise alterações recentes de configuração

2. Inicialize o Git

Tenha sempre controle de versão antes de usar modos permissivos
Faça commit do trabalho atual para ter um ponto de partida limpo
Oferece a opção de rollback caso ocorram problemas

3. Verifique o saldo de créditos

Confirme se há créditos suficientes para o trabalho planejado
Recarregue se necessário antes de iniciar tarefas complexas
Evite interrupções no meio da tarefa por falta de créditos

Durante o desenvolvimento

1. Use os modos de execução apropriados

Manual Accept para código desconhecido
Plan Mode para alterações complexas
Auto-Run apenas com a rede de segurança do Git
Adapte o modo ao nível de risco

2. Monitore o desempenho

Fique atento à queda na qualidade das respostas
Note tempos de resposta mais lentos
Inicie novas sessões quando o desempenho cair
Acompanhe o uso de contexto manualmente

3. Prompts claros e específicos

Reduza erros causados por solicitações mal compreendidas
Inclua contexto e restrições relevantes
Faça referência a padrões existentes
Especifique claramente o escopo

Após os erros

1. Aprenda com os padrões

Anote o que disparou os erros
Identifique condições reproduzíveis
Ajuste o fluxo de trabalho para evitar os gatilhos
Compartilhe as descobertas com a comunidade

2. Documente as soluções alternativas

Mantenha anotações sobre soluções eficazes
Compartilhe com os membros da equipe
Contribua para o conhecimento da comunidade
Relate à equipe do Verdent para correções

3. Atualize a configuração

Ajuste as configurações com base na experiência
Otimize para o seu fluxo de trabalho
Configure regras para evitar problemas
Mantenha a documentação em AGENTS.md