Chiunque abbia pubblicato un bot Discord lo ha già visto: un martedì normale, poi all'improvviso increased api errors ovunque e metà dei comandi che falliscono. Google Trends ha registrato la frase come termine di ricerca "in forte crescita" a metà del 2026; succede abbastanza spesso da far sì che gli utenti la cerchino direttamente. Ecco come sopravvivere e cosa l'API del server Noxyr ha preso da queste lezioni.

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

Le tre modalità di guasto più gravi dell'API di Discord

  • Interruzione globale / parziale: visibile su discordstatus.com. Sintomi: qualsiasi richiesta può fallire, il gateway può cadere, i tempi di risposta si impennano ovunque.
  • 429 Too Many Requests: hai superato il limite di un bucket. Discord restituisce un header Retry-After che ti dice esattamente quanto attendere.
  • Sessione non valida sul gateway: la tua sessione WebSocket è scaduta. Riconnettiti con il tuo token di ripresa; se non funziona, esegui un nuovo identify.

Progetta per i guasti, non per il sereno

  • Rispetta Retry-After. Non riprovare con un tuo timer. Attendi esattamente il tempo che Discord indica, poi riprova una sola volta. I bot che martellano gli 429 vengono bannati.
  • Backoff esponenziale con jitter. Sugli errori 5xx, attendi 1s, 2s, 4s, 8s, più un piccolo scarto casuale così un gruppo di riavvii non causa un picco simultaneo.
  • Interrompi le chiamate non critiche. Se il tuo bot pubblica un riepilogo settimanale e l'API di Discord è degradata, salta questa esecuzione invece di accumulare altre richieste. Il riepilogo può aspettare; l'interruzione no.
  • Metti in cache tutto ciò che non è in tempo reale. Nomi dei server, elenchi dei canali, ID dei ruoli: salvali in locale. Durante un'interruzione, i dati in cache ti permettono di continuare a rispondere.
  • Mostra lo stato. Se i comandi del tuo bot falliscono perché Discord è giù, dillo agli utenti. Una riga come "Discord sta riscontrando problemi" è meglio di timeout silenziosi.

Come l'API del server Noxyr applica queste lezioni

L'API del server Noxyr non è l'API di Discord: legge il proprio database, ma gli stessi principi valgono e hanno influenzato il suo design:

  • Errori prevedibili: ogni errore è un JSON con un codice error stabile. Nessun HTML, nessun formato variabile.
  • Header di rate limit: header RateLimit-* standardizzati, così i client rallentano prima di raggiungere un 429.
  • Degradazione controllata: l'endpoint /api/v1/server ricade sui dati di guild in cache quando il recupero da Discord fallisce.
  • Nessun guasto a cascata: ogni endpoint fallisce in modo indipendente. Se Discord è giù, il tuo endpoint di analisi dei ticket non si rompe, perché legge da Mongo e non da Discord.
  • Interruttore di emergenza immediato: disattivare una chiave o un ambito ha effetto alla richiesta successiva, senza bisogno di riavvio.

Procedura quando Discord va storto

  • 1. Controlla prima discordstatus.com: il problema riguarda solo te?
  • 2. Guarda i tuoi log degli errori: 429, 5xx, disconnessioni dal gateway.
  • 3. Se il problema è di Discord: sospendi le scritture non critiche, rispetta Retry-After, aspetta che passi.
  • 4. Se il problema è tuo: controlla i deploy recenti, le invalidazioni della cache, le nuove funzioni.
  • 5. Comunica. Una breve nota onesta nel canale di supporto evita 100 segnalazioni duplicate.

Altro sul livello API: l'API del server Noxyr, API di Discord vs API di Noxyr, principi di progettazione delle API.