Cualquiera que haya publicado un bot de Discord lo ha visto: un martes normal y de repente increased api errors por todas partes y la mitad de tus comandos fallan. Google Trends registró la frase como término de búsqueda "en auge" a mediados de 2026; ocurre con tanta frecuencia que los usuarios finales la buscan directamente. Aquí tienes cómo sobrevivir a ello y qué toma la API de servidor de Noxyr de esas lecciones.

A request gets a 429, waits out a countdown, then retries and succeeds with a 200. Server 429 200 3 2 1 Retry-After

Los tres fallos más importantes de la API de Discord

  • Caída total / caída parcial: visible en discordstatus.com. Síntomas: cualquier petición puede fallar, la pasarela puede cortarse, la latencia se dispara en todo.
  • 429 Too Many Requests: has superado el límite de un bucket. Discord devuelve una cabecera Retry-After que indica exactamente cuánto hay que esperar.
  • Sesión no válida en la pasarela: tu sesión de WebSocket está caducada. Reconecta con tu token de reanudación; si eso falla, haz un identify nuevo.

Diseña para el fallo, no para el buen tiempo

  • Respeta Retry-After. No reintentes con tu propio temporizador. Espera exactamente lo que te indica Discord y reintenta una vez. Los bots que martillean los 429 acaban baneados.
  • Backoff exponencial con jitter. Ante errores 5xx, espera 1 s, 2 s, 4 s, 8 s, más un pequeño desfase aleatorio para que una flota de reinicios no se estampe a la vez.
  • Corta el circuito de las llamadas no críticas. Si tu bot publica un resumen semanal y la API de Discord está degradada, sáltate esa ejecución en lugar de cargar más. El resumen puede esperar; la caída no.
  • Guarda en caché todo lo que no sea en tiempo real. Nombres de servidores, listas de canales, IDs de roles: guárdalos en local. Durante una caída, los datos en caché te mantienen funcionando.
  • Muestra el estado. Si los comandos de tu bot fallan porque Discord está caído, avisa a los usuarios. Un "Discord está teniendo problemas en este momento" de una línea es mejor que los timeouts silenciosos.

Cómo aplica la API de servidor de Noxyr estas lecciones

La API de servidor de Noxyr no es la API de Discord, lee de su propia base de datos, pero se aplican los mismos principios y eso marcó su diseño:

  • Errores predecibles: cada fallo es JSON con un código error estable. Nada de HTML ni formatos variables.
  • Cabeceras de límite de frecuencia: cabeceras RateLimit-* estandarizadas para que los clientes reduzcan el ritmo antes de llegar al 429.
  • Degradación elegante: el endpoint /api/v1/server recurre a los datos de servidor en caché cuando falla la consulta a Discord por debajo.
  • Sin fallos en cascada: cada endpoint falla de forma independiente. Que Discord esté caído no rompe tu endpoint de analíticas de tickets, porque lee de Mongo, no de Discord.
  • Interruptor de emergencia instantáneo: desactivar una clave o un ámbito surte efecto en la siguiente petición, sin reiniciar nada.

Guía de actuación cuando Discord se complica

  • 1. Mira primero discordstatus.com: ¿es solo a ti?
  • 2. Revisa tus propios logs de errores: 429, 5xx, desconexiones de la pasarela.
  • 3. Si es Discord: pausa las escrituras no críticas, respeta Retry-After y espera a que pase.
  • 4. Si eres tú: revisa los despliegues recientes, las invalidaciones de caché y las funciones nuevas.
  • 5. Comunícalo. Una nota breve y sincera en tu canal de soporte evita 100 reportes duplicados.

Más sobre la capa de la API: la API de servidor de Noxyr, API de Discord frente a API de Noxyr, principios de diseño de APIs para bots de Discord.