Intestazione Retry-After: tempo di attesa prima di riprovare

Retry-After è un'intestazione di risposta HTTP che indica all'app quanto tempo attendere prima che invii la richiesta successiva. Il valore è un numero di secondi o una data HTTP. Quando un'API lo invia, è la risposta più affidabile a "quando posso riprovare?" perché proviene dal server che ha disattivato la richiesta. Per altre informazioni, vedere RFC 9110, sezione 10.2.3.

Come si presenta Retry-After

L'intestazione ha 2 formati. L'app deve gestire entrambi.

Format Example Che cosa significa
Seconds Retry-After: 120 Attendere 120 secondi (2 minuti) da quando si è ricevuta la risposta. Il valore è un numero intero non negativo.
data HTTP Retry-After: Fri, 31 Dec 1999 23:59:59 GMT Non inviare di nuovo la richiesta prima di questo momento. La data è sempre in GMT.

I server inviano Retry-After con questi codici di stato:

Status Cosa Retry-After significa Source
429 Too Many Requests Tempo di attesa prima dell'invio di una nuova richiesta. Il server può includerlo. RFC 6585, sezione 4
503 Service Unavailable Per quanto tempo si prevede che il servizio non sia disponibile. Il server può includerlo. RFC 9110, sezione 15.6.4
413 Content Too Large Se la condizione è temporanea, il server deve dire dopo quanto tempo è finito. RFC 9110, sezione 15.5.14
Qualsiasi 3xx reindirizzamento Tempo minimo di attesa prima di seguire il reindirizzamento. RFC 9110, sezione 10.2.3

L'intestazione è facoltativa. Alcune API usano invece le proprie intestazioni. Ad esempio, GitHub indica quando il limite viene reimpostato tramite x-ratelimit-reset. Per altre informazioni, vedere limite di frequenza dell’API di GitHub superato.

Come gestire Retry-After

  1. Leggere entrambi i formati. Se il valore è un numero, è espresso in secondi. In caso contrario, analizzarlo come data e sottrarre la data/ora corrente. Se la data è già in passato, è possibile riprovare subito.
  2. Attendere almeno per il tempo indicato nell'intestazione. Riprovare prima di solito consente di ottenere un altro 429 o 503. Alcune API continuano a conteggiare le richieste mentre applicano il throttling, quindi nuovi tentativi effettuati troppo presto possono prolungare l'attesa. Ad esempio, vedere Microsoft Graph linee guida sulla limitazione della velocità.
  3. Ripiegare sul backoff con jitter quando l'header è assente. Raddoppiare l'attesa dopo ogni tentativo non riuscito, aggiungere una quantità casuale in modo che molti client non riprovano nello stesso momento e limitare l'attesa.
  4. Limita i tentativi. Dopo alcuni tentativi, restituire l'errore al chiamante.
  5. Verificare se riprovare può aiutare. Alcune API restituiscono 429 quando i crediti o il limite di spesa sono esauriti. Aspettare non risolverà quelli. Per un esempio, vedere OpenAI insufficient_quota e credit_balance_exhausted.
function retryDelayMs(response, attempt) {
  const value = response.headers.get('retry-after');
  if (value) {
    const seconds = Number(value);
    const ms = Number.isNaN(seconds) ? Date.parse(value) - Date.now() : seconds * 1000;
    if (!Number.isNaN(ms)) {
      return Math.max(ms, 0);
    }
  }
  // No usable header: exponential backoff with jitter, capped at 30 seconds
  return Math.random() * Math.min(30_000, 1_000 * 2 ** attempt);
}

Molti SDK gestiscono Retry-After automaticamente, ma solo fino a quando non esauriscono i tentativi. Il codice riceve quindi l'errore.

SDK Che cosa fa per impostazione predefinita
.NET standard resilience handler Ritenta 408, 429e 5xx risposte fino a 3 volte con backoff esponenziale e instabilità. Viene usato Retry-After per il ritardo perché ShouldRetryAfterHeader per impostazione predefinita è true.
Microsoft Graph SDK Usare Retry-After quando è presente ed eseguire il fallback a backoff esponenziale quando non lo è. Le richieste all'interno di un batch JSON non vengono ritentate automaticamente.
OpenAI Python SDK Riprovare gli errori di connessione e 408, 409, 429e 5xx le risposte 2 volte con un backoff esponenziale breve. Impostare max_retries per modificarlo.

Controllare la documentazione dell'SDK per ottenere i criteri esatti e verificare cosa accade dopo che anche l’ultimo tentativo di retry fallisce.

Come testare che l'app gestisca Retry-After

Raramente si ottiene un Retry-After po ' di sviluppo, e quando si esegue, non è possibile controllarne il valore. Quindi il modo in cui si testa questo decide se si trovano i bug prima che gli utenti facciano.

Avvicinarsi Cosa trovi Quello che ti manca
Attendere l'ambiente di produzione Guasti reali Tutto, fino a quando un utente non ci clicca
Simula l'API nei test oppure lascia che il tuo agente di coding scriva il mock Se il codice analizza l'intestazione Sia che il client HTTP reale o l'SDK attenda abbastanza a lungo e che cosa l'API invii realmente. L'app richiede anche un'opzione di sola prova per raggiungere il mock.
Chiama l'API reale fino a quando non ti limita la frequenza delle richieste Comportamento reale Non è possibile attivare su richiesta una risposta soggetta a throttling e si consuma la quota reale
Intercettare il traffico reale dell'app e restituire risposte rallentate su richiesta Se l'SDK reale e il criterio di retry attendono per il tempo indicato dall'header Niente nella tua app cambia, quindi non testa il codice in isolamento. Mantieni i test unitari per quello.

Provalo nella tua app

Dev Proxy intercetta le richieste dell'app alle API scelte e restituisce 429 risposte con un'intestazione Retry-After , mentre l'app continua a chiamare gli URL reali. RetryAfterPlugin ricorda quando ogni richiesta limitata può essere ritentata. Se l'app chiama lo stesso URL prima di tale ora, Dev Proxy lo segnala e limita nuovamente la richiesta. Il plug-in tiene traccia solo delle risposte 429.

Nel file degli errori per GenericRandomErrorPlugin, imposta il Retry-After valore di una 429 risposta su @dynamic e Dev Proxy compila il numero di secondi e ne tiene traccia automaticamente.

Per provarlo, scarica un preset che usa entrambi i plugin e avvia Dev Proxy con questo:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Eseguire quindi l'app come di consueto e osservare le operazioni eseguite. Per installare Dev Proxy, vedere Configurare Dev Proxy.

Passaggi successivi

Verificare che l'applicazione gestisca correttamente la limitazione

Vedere anche

  • Last updated on