Manejo y recuperación de errores

Comprender cómo interpretar los errores, responder a ellos e informarlos te ayuda a mantener sesiones de desarrollo productivas con Verdent for VS Code.

Lo que aprenderás

Tipos de errores comunes y sus causas
Cómo interpretar los mensajes de error de forma eficaz
Pasos sistemáticos de resolución de problemas
Cuándo esperar y cuándo actuar
Cómo informar problemas al equipo de Verdent

La documentación completa sobre errores está en desarrollo actualmente. La información a continuación cubre las categorías de errores más frecuentes. Para escenarios de error específicos, contacta a support@verdent.ai o visita la comunidad de Discord.

Errores de servidor sobrecargado

Ocurren durante períodos de mucho tráfico
Limitaciones temporales de capacidad
Acción: Espera de 5 a 10 minutos y vuelve a intentarlo

Errores internos del servidor

Problemas de procesamiento en el backend
Interrupciones temporales del servicio
Acción: Espera y vuelve a intentarlo; suele resolverse automáticamente

503 Service Unavailable

No hay servidores upstream en buen estado
Problemas temporales de infraestructura
Acción: Espera a que se recupere el servicio

Errores de límite de frecuencia

Se superaron las cuotas de solicitudes
Protecciones de limitación de API
Acción: Espera a que se restablezca el límite de frecuencia y reduce la frecuencia de solicitudes

Credenciales inválidas o vencidas
Problemas de tiempo de espera de sesión
Acción: Vuelve a autenticarte a través del Centro de usuario y verifica que la suscripción esté activa

Problemas de conectividad de red
Firewall o VPN que bloquean las conexiones
Restricciones de red corporativa
Acción: Comprueba la conexión de red y prueba con una red diferente

Ajustes o preferencias inválidos
Archivos de configuración corruptos
Acción: Revisa los cambios de ajustes recientes y verifica la configuración

Permisos insuficientes del sistema de archivos
Restricciones de acceso al espacio de trabajo
Acción: Comprueba los permisos de archivos y carpetas y verifica el acceso al espacio de trabajo

Interpretación de los mensajes de error

La guía detallada de interpretación de mensajes de error está en desarrollo. Para mensajes de error específicos que encuentres, usa el botón de comentarios o la comunidad de Discord para obtener ayuda.

Los errores del lado del servidor son temporales y suelen resolverse con esperar. No se requiere ninguna acción más que reintentar después de unos minutos.

Busca estas palabras clave:

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

Qué hacer:

Espera de 5 a 10 minutos antes de reintentar
Continúa con el trabajo de desarrollo local
Revisa los cambios de código realizados hasta ahora
Confirma el trabajo actual en Git

Regla general: Si el mensaje de error menciona el estado del servidor, la capacidad o los límites de frecuencia, es temporal. Se trata de problemas de infraestructura que se resuelven automáticamente.

Los errores temporales del servidor (502, 503, 504) suelen resolverse en minutos. Espera de 2 a 3 minutos antes de reintentar.

Cuándo escalar:

El error persiste más de 15 minutos
Consulta Discord para ver informes de interrupciones
Busca actualizaciones en la página de estado

Los errores del lado del cliente requieren acción de tu parte. No se resolverán con esperar.

Busca estos indicadores:

Mensajes relacionados con autenticación o credenciales
Errores de configuración o ajustes
Errores de permisos de archivos
Fallas de conexión de red

Qué hacer:

Errores de autenticación: Vuelve a autenticarte a través del Centro de usuario y verifica que la suscripción esté activa
Errores de configuración: Revisa los cambios de ajustes recientes y verifica los archivos de configuración
Errores de permisos: Comprueba los permisos de archivos y carpetas y verifica el acceso al espacio de trabajo
Errores de red: Prueba la conexión a internet, prueba con una red diferente y revisa la VPN/firewall

Regla general: Si el error menciona autenticación, configuración, permisos o ajustes locales, debes tomar una acción correctiva.

Pasos de resolución de problemas:

Lee el mensaje de error completo para obtener orientación específica
Identifica qué componente informó el error (autenticación, configuración, permisos, red)
Toma una acción específica según el tipo de error
Verifica la solución reintentando la operación original

Lectura del contexto del error

Cuando ocurren errores:

Lee el mensaje de error completo: No omitas detalles
Anota los códigos de error: Los códigos específicos ayudan a diagnosticar problemas
Identifica el componente: Qué sistema informó el error (servidor, API, local)
Verifica el momento: ¿Ocurrió de inmediato o tras una demora?

Resolución de problemas sistemática

Sigue estos pasos progresivos cuando Verdent se comporte de forma inesperada, empezando por las acciones menos disruptivas.

Respuesta inicial

Espera y observa

Comprueba si el comportamiento es constante o intermitente. Anota qué acción desencadenó el comportamiento inesperado. No asumas de inmediato que algo está fallando: muchos problemas son temporales.

Reinicio básico

Reinicia Verdent for VS Code (cierra y vuelve a abrir VS Code). A menudo resuelve estados bloqueados o problemas de rendimiento. Este es el primer paso de resolución de problemas más sencillo.

Resolución de problemas progresiva

Si el reinicio básico no resuelve el problema:

Sigue los pasos de resolución de problemas sistemática en orden; saltarse pasos a menudo significa pasar por alto la causa raíz.

Comprueba la conexión de red

Prueba la conexión a internet con otros sitios web. Prueba con una red diferente (punto de acceso móvil) para descartar problemas de firewall/VPN. Comprueba si la red corporativa está bloqueando las conexiones.

Verifica la configuración

Comprueba que sigues autenticado. Verifica que la suscripción esté activa en el Centro de usuario. Revisa los cambios de ajustes recientes que podrían afectar el comportamiento.

Busca ayuda

Consulta la comunidad de Discord para ver informes similares: https://discord.com/invite/NGjXEZcbJq. Usa el botón de comentarios para informar el problema. Incluye una descripción del comportamiento inesperado y los pasos para reproducirlo.

Lo que NO debes hacer

Evita estas acciones para problemas temporales:

No reinstales Verdent de inmediato
No borres la caché ni los datos de la aplicación de VS Code
No modifiques los ajustes del sistema por problemas temporales
No reinicies el equipo a menos que otras aplicaciones también se vean afectadas

En Manual Accept Mode, nunca apruebes operaciones destructivas (rm, DROP, DELETE) sin revisar cuidadosamente el comando exacto.

¿Por qué? Estas acciones consumen mucho tiempo y rara vez solucionan los problemas. La mayoría se resuelven con un simple reinicio o esperando a que se aclaren los problemas temporales del servidor.

Cuándo esperar y cuándo actuar

Comprender si esperar o tomar acción evita esfuerzos de resolución de problemas desperdiciados.

Estos errores se resuelven automáticamente: no se necesita ninguna acción más que esperar y reintentar.

Errores de sobrecarga o capacidad del servidor:

Mensajes de "Overloaded" o "at capacity"
Períodos de mucho tráfico
Interrupciones temporales del servicio

Límite de frecuencia:

Mensajes de "Rate limit" o "quota exceeded"
Demasiadas solicitudes en poco tiempo
Protección de limitación de API

Problemas de conexión intermitentes:

Solicitudes fallidas ocasionales que tienen éxito al reintentar
Interrupciones de red
Caídas breves de conectividad

Qué hacer mientras esperas:

Continúa con el trabajo de desarrollo local
Revisa los cambios de código realizados hasta ahora
Planifica los próximos pasos o tareas pendientes
Confirma el trabajo actual en Git

Cuánto esperar:

Espera estándar: de 5 a 10 minutos
Si sigue fallando después de 10 minutos, pasa a la resolución de problemas
Consulta Discord para ver informes de problemas generalizados

Estos errores no se resolverán con esperar: debes tomar una acción correctiva.

Fallas de autenticación:

Sesión vencida → Vuelve a autenticarte a través del Centro de usuario
Credenciales inválidas → Verifica que la suscripción esté activa
Necesidad de volver a autenticarse → Consulta el Centro de usuario

Errores persistentes (más de 10 minutos):

El mismo error repetidamente tras varios reintentos → Inicia la resolución de problemas
Patrón de fallas constante → Comprueba la configuración
El error persiste tras los reinicios → Verifica el entorno

Problemas de configuración:

Ajustes cambiados recientemente → Revisa y revierte los cambios
Nueva configuración o instalación → Verifica los archivos de configuración
Entorno de red cambiado → Prueba la conectividad

Errores de permisos:

Acceso al sistema de archivos denegado → Comprueba los permisos de archivos y carpetas
Restricciones del espacio de trabajo → Verifica el acceso al espacio de trabajo
Permisos de carpeta → Concede los permisos necesarios

Problemas de red:

Incapacidad total de conectarse → Prueba la conexión a internet
VPN o firewall que bloquean → Prueba con una red diferente
Restricciones de red corporativa → Contacta al soporte de TI

Regla de decisión:

Errores de servidor/frecuencia → Espera
Autenticación/configuración/permisos/red → Actúa de inmediato
¿No estás seguro? → Espera de 5 a 10 minutos primero y luego actúa si persiste

Proporcionar contexto del error

Cuando busques ayuda o informes problemas, incluye un contexto completo para un diagnóstico más rápido.

Información esencial

Detalles del error:

Texto exacto del mensaje de error (cópialo y pégalo, no lo parafrasees)
Código de error si se proporciona
Marca de tiempo de cuándo ocurrió el error
Frecuencia (única vez, intermitente, constante)

Entorno:

Versión de Verdent for VS Code
Versión de VS Code
Sistema operativo y versión
Entorno de red (hogar, corporativo, VPN)

Pasos para reproducir:

Qué intentabas hacer
Prompts o comandos exactos utilizados
Archivos o contexto involucrados
Acciones realizadas antes del error

Contexto:

Qué modo de ejecución estabas usando
Tamaño y complejidad del espacio de trabajo
Cambios de configuración recientes
Operaciones similares previas exitosas

Ejemplo de informe de error

Buen formato de informe de error:

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

Qué hace esto eficaz

Texto exacto del mensaje de error
Detalles completos del entorno
Pasos de reproducción claros
Comparación con escenarios que funcionan
Contexto adicional sobre patrones

Informar problemas

Ubicación: Barra superior del panel de Verdent

Qué hace:

Abre una ventana emergente para enviar problemas y sugerencias
Canal directo con el equipo de Verdent
Ideal para informes de errores y solicitudes de funciones

Cuándo usarlo:

Errores confirmados con pasos de reproducción claros
Solicitudes de funciones con casos de uso específicos
Cuando se necesita comunicación directa con el equipo
Problemas no urgentes que requieren investigación

Qué incluir:

Descripción clara del problema
Mensajes de error (texto exacto)
Pasos para reproducir
Comportamiento esperado frente al real
Versión y plataforma de Verdent
Cuándo comenzó el problema

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

Qué ofrece:

Comunidad activa de usuarios y miembros del equipo de Verdent
Asistencia de resolución de problemas en tiempo real
Compartir problemas con capturas de pantalla
Obtener ayuda de usuarios con experiencia
Debate comunitario y soluciones alternativas

Cuándo usarla:

Problemas urgentes que requieren un debate inmediato
Resolución de problemas compleja que necesita ida y vuelta
Aportes de la comunidad sobre mejores prácticas
Preguntas rápidas antes de presentar informes formales
Compartir soluciones alternativas con la comunidad

Tipo de problema	Usa el botón de comentarios	Usa Discord
Error confirmado con pasos de reproducción	✓
Solicitud de función	✓
Resolución de problemas urgente necesaria		✓
Problema complejo que necesita debate		✓
Pregunta rápida		✓
Quieres aportes de la comunidad		✓
Informe formal de error	✓
Ayuda general		✓

Qué NO informar:

Errores temporales del servidor (menos de 10 minutos)
Períodos de mucho tráfico
Problemas ya documentados
Comportamiento esperado

En su lugar: Espera a que pasen los problemas temporales, consulta Discord para ver informes recientes y revisa la documentación.

Mejores prácticas de prevención

Las prácticas proactivas reducen la frecuencia de errores y mejoran la recuperación cuando ocurren.

Usa un lenguaje específico en los prompts e incluye contexto de archivos relevante para prevenir muchos errores comunes antes de que ocurran.

Antes de empezar a trabajar

1. Verifica la configuración

Comprueba el estado de autenticación en el Centro de usuario
Confirma que la suscripción esté activa
Asegura una conexión de red estable
Revisa los cambios de configuración recientes

2. Inicializa Git

Ten siempre control de versiones antes de usar modos permisivos
Confirma el trabajo actual para tener un punto de partida limpio
Proporciona una opción de reversión si ocurren problemas

3. Comprueba el saldo de créditos

Verifica que tengas créditos suficientes para el trabajo planificado
Recarga créditos si es necesario antes de iniciar tareas complejas
Evita interrupciones a mitad de la tarea por agotamiento de créditos

Durante el desarrollo

1. Usa los modos de ejecución apropiados

Aceptación manual para código desconocido
Plan Mode para cambios complejos
Ejecución automática solo con la red de seguridad de Git
Adapta el modo al nivel de riesgo

2. Supervisa el rendimiento

Atento a la degradación de la calidad de las respuestas
Anota los tiempos de respuesta más lentos
Inicia nuevas sesiones cuando el rendimiento decaiga
Realiza un seguimiento manual del uso del contexto

3. Prompts claros y específicos

Reduce los errores por solicitudes mal entendidas
Incluye contexto y restricciones relevantes
Haz referencia a patrones existentes
Especifica el alcance con claridad

Después de los errores

1. Aprende de los patrones

Anota qué desencadenó los errores
Identifica las condiciones reproducibles
Ajusta el flujo de trabajo para evitar los desencadenantes
Comparte tus hallazgos con la comunidad

2. Documenta las soluciones alternativas

Mantén notas sobre las soluciones eficaces
Compártelas con los miembros del equipo
Contribuye al conocimiento de la comunidad
Infórmalas al equipo de Verdent para que las solucionen

3. Actualiza la configuración

Ajusta los ajustes según la experiencia
Optimiza para tu flujo de trabajo
Configura reglas para prevenir problemas
Mantén la documentación de AGENTS.md