¿Tu bot de Discord está en línea pero no responde? Lista de diagnóstico

Paso 0: que el error se vea

La mayoría de los bots "silenciosos" lanzan errores que nadie ve. Antes que nada:

Registra toda promesa rechazada sin manejar: process.on("unhandledRejection", console.error) en Node.js, o configura logging en discord.py (discord.utils.setup_logging() o el handler por defecto de client.run).
Envuelve los handlers de interacciones en try/catch y registra el objeto de error, que incluye el code de Discord.
Revisa los logs del hosting, no solo tu terminal. En Docker: docker compose logs -f.

Luego recorre la lista en orden.

1. ¿De verdad está conectado?

Síntoma	Causa probable
Nunca se conecta, código de cierre `4004`	Token inválido. Restablécelo en el Developer Portal y actualiza la variable de entorno.
Se desconecta al instante, código `4014`	Tu código pide un intent privilegiado que no está activado en el portal.
En línea y luego fuera tras unos minutos	El proceso falla o el hosting lo suspende. Mira cómo mantener un bot en línea 24/7.
Responden dos copias	Hay dos instancias con el mismo token (un despliegue viejo, tu laptop). Detén una.

2. Comandos con prefijo: el intent de Message Content

Si el bot reacciona a comandos de barra pero no a !ping, probablemente el texto del mensaje llega vacío. Desde que Discord hizo de Message Content un intent privilegiado, un bot sin él recibe content vacío en la mayoría de los mensajes, salvo en DMs, mensajes que lo mencionan y sus propios mensajes.

Arregla ambos lados:

Developer Portal > tu app > Bot > activa Message Content Intent.
Pídelo en el código:

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
});

intents = discord.Intents.default()
intents.message_content = True
client = discord.Client(intents=intents)

Mejor a largo plazo: pasa a comandos de barra, que no necesitan intents privilegiados. Detalles en los intents del gateway de Discord explicados.

3. No aparecen los comandos de barra

Sin registrar. Los comandos se registran por la API, aparte del inicio de sesión. Ejecuta tu script; mira comandos de barra en discord.js v14.
Scope incorrecto. El bot debe invitarse con bot y applications.commands. Vuelve a invitarlo con una URL de la calculadora de permisos; no lo expulsa.
ID de servidor equivocado. Los comandos registrados en tu servidor de pruebas no existen en ningún otro.
Cliente desactualizado. Reinicia el cliente de Discord (Ctrl+R en escritorio) tras cambiar comandos.
Los permisos los ocultan. default_member_permissions o la configuración de Integraciones del servidor pueden ocultar un comando a los miembros normales.

4. "La aplicación no ha respondido"

No confirmaste la interacción en 3 segundos. Causas típicas:

Una API o consulta lenta antes de reply(). Llama primero a deferReply() y luego a editReply().
El handler lanzó un error antes de responder. Tus logs (paso 0) lo mostrarán.
El listener no está registrado, por ejemplo un interactionCreate dentro de un archivo que nunca importas.

Si respondes demasiado tarde también verás 10062 Unknown interaction. Si respondes dos veces, 40060 Interaction has already been acknowledged: usa followUp() o editReply() para el segundo mensaje.

5. Errores de permisos en ciertos canales

Código	Significado	Solución habitual
`50001`	Missing Access	El bot no ve el canal (`Ver canal` denegado por un permiso específico) o no está en ese servidor.
`50013`	Missing Permissions	Ve el canal pero le falta `Enviar mensajes`, `Insertar enlaces`, `Adjuntar archivos`, `Enviar mensajes en hilos` o un requisito de jerarquía de roles.

Los permisos específicos de canal y categoría pesan más que los permisos de rol del servidor; por eso un bot funciona en un canal y no en otro. Para acciones de moderación, el rol más alto del bot debe estar por encima del rol más alto del miembro.

6. Funciona en local pero no en el hosting

Falta una variable de entorno (el token, la URL de la base de datos). Valídalas con el validador de .env.
Otra versión de Node.js o Python. Fíjala (engines en package.json, python:3.12-slim en Docker).
El hosting solo corre procesos web y detiene tu worker por no abrir un puerto. Usa un servicio de tipo worker o un hosting pensado para procesos 24/7: hosting 24/7 para bots de Discord.

7. Límites de tasa

Un bot que envía muchos mensajes puede ser limitado. Las respuestas HTTP 429 incluyen retry_after; librerías como discord.js y discord.py encolan y esperan solas, así que el síntoma es demora, no error. Si ves pausas largas, busca ciclos que editan o envían mensajes demasiado seguido. Mira los límites de tasa explicados.

Preguntas frecuentes

¿Necesito verificar mi bot para usar intents?

Por debajo de 100 servidores puedes activar los intents privilegiados tú mismo en el portal. Los bots verificados (obligatorio al llegar a 100 servidores) deben solicitar cada intent privilegiado que usen.

Mi bot responde por DM pero no en servidores. ¿Por qué?

Los DMs incluyen el contenido del mensaje sin el intent privilegiado y no tienen permisos por canal. En servidores, revisa el intent de Message Content y los permisos del canal.

Ayer funcionaba y hoy no. ¿Qué cambió?

Revisa si el token se restableció (un escaneo de filtraciones puede provocarlo), si un despliegue dejó una segunda instancia o si alguien cambió los permisos del canal.

Fuentes

Discord Developer Docs, intents y códigos de cierre del gateway: discord.com/developers/docs/events/gateway
Discord Developer Docs, códigos de error JSON: discord.com/developers/docs/topics/opcodes-and-status-codes
Discord Developer Docs, recibir y responder interacciones: discord.com/developers/docs/interactions/receiving-and-responding
Discord Developer Docs, permisos: discord.com/developers/docs/topics/permissions
Discord Support, preguntas sobre el intent de Message Content: support-dev.discord.com