429 Troppe richieste: cosa significa e come gestirlo

Un'API restituisce 429 Too Many Requests quando l'app ha inviato più richieste di quante l'API consente in un periodo di tempo. La richiesta stessa va bene. L'hai inviato troppo spesso, quindi l'API l'ha rifiutato. Se si attende e lo si invia di nuovo, in genere ha esito positivo. La risposta include spesso un'intestazione Retry-After che indica quanto tempo attendere. Per altre informazioni, vedere RFC 6585, sezione 4.

Che aspetto ha un 429 nelle API più diffuse

Ogni API implementa limiti di frequenza in modo diverso. Il codice di stato, le intestazioni e il corpo dell'errore variano, quindi il codice che gestisce correttamente un'API può non gestire correttamente la successiva.

Come gestire un 429

1. Decidi se riprovare o meno. Se l'errore indica che la quota, i crediti o il limite di spesa sono esauriti, i tentativi non saranno utili. Dillo all'utente e avvisa te stesso.
2. Attendere per tutto il tempo richiesto dall'API. Se la risposta riporta Retry-After, attendere tale tempo. Si tratta di un numero di secondi o di una data HTTP. Se l'API usa invece gli header di limitazione della frequenza, ad esempio GitHub x-ratelimit-reset, attendere fino all'ora di reimpostazione.
3. Altrimenti, fare marcia indietro. Senza un suggerimento dall'API, riprovare con backoff esponenziale e instabilità casuale e arrestarsi dopo alcuni tentativi.
4. Indicare all'utente cosa sta accadendo. "Occupato, riprovare in 5 secondi" batte uno spinner che non termina mai.
5. Rallenta prima del successivo errore 429. Se l'API invia intestazioni limite di frequenza, usare il conteggio rimanente per gestire le richieste.

async function fetchWithRetry(url, options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429 || attempt === attempts) {
      return response;
    }
    const retryAfter = response.headers.get('retry-after');
    const waitMs = retryAfter
      ? (isNaN(retryAfter) ? new Date(retryAfter) - Date.now() : retryAfter * 1000)
      : 2 ** attempt * 1000 + Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 0)));
  }
}

Molti SDK riprovano a 429s. Ad esempio, OpenAI Python SDK ritenta 2 volte per impostazione predefinita e il gestore di resilienza standard di .NET ritenta 3 volte e rispetta Retry-After. Quando l'SDK esaurisce i tentativi, il codice riceve l'errore, quindi richiede ancora un piano.

Come testare che l'app gestisca 429

Raramente si vede un 429 mentre si sviluppa. L'API è veloce, sei l'unico utente e i dati di test sono di piccole dimensioni. Quindi, il modo in cui si testa la gestione 429 decide se si trovano i bug prima che lo facciano gli utenti.

Provalo nella tua app

Dev Proxy intercetta le richieste dell'app alle API scelte e restituisce 429, con le intestazioni e il formato di errore dell'API, mentre l'app continua a chiamare gli URL reali. Indica anche quando l'app ritenta prima che scada il tempo Retry-After.

Scaricare il set di impostazioni per l'API che l'app chiama e avviare Dev Proxy con esso:

devproxy config get github-rate-limiting
devproxy --config-file "~dataFolder/configs/github-rate-limiting/.devproxy/devproxyrc.json"

Eseguire quindi l'app come di consueto e osservare cosa fa. Per installare Dev Proxy, vedere Configurare Dev Proxy.

Passaggi successivi

Vedere anche

• Che cos'è la limitazione della frequenza?
• Che cos'è la limitazione?
• Testa come l'app gestisce i limiti di frequenza dell'API di GitHub
• Testare il modo in cui l'app gestisce i limiti di frequenza OpenAI
• Testare i tentativi e i timeout nelle app .NET