Vai al contenuto principale
Quando progetti i retry di un job in coda, considera separatamente quattro domande: quante volte tentare, fino a quando tentare, quante eccezioni tollerare e quanti secondi attendere prima del tentativo successivo. In Laravel 13 puoi dichiarare ognuna di queste con attributi e metodi del job.
Questa pagina si riferisce a Laravel 13 e a Framework v13.42.0. Non tratta l’uso di base delle code, ma come si combinano le impostazioni di retry e quale ha la precedenza.

Separare il numero di tentativi dalla scadenza

In Laravel un “tentativo” non è solo una chiamata riuscita a handle(). Anche le eccezioni non gestite, release(), i rilasci da parte di middleware come WithoutOverlapping o RateLimited e i timeout consumano tentativi. Se non specifichi nulla, il worker tenta il job una sola volta.

Tries: limitare il numero di tentativi

Puoi dichiarare un limite per singolo job con l’attributo Tries. L’impostazione del job ha la precedenza su --tries del worker.
Per decidere il limite in base a condizioni a runtime, usa il metodo tries(). Questo metodo ha la precedenza sull’attributo Tries.

RetryFor: definire una finestra temporale

Per limitare i retry in base al tempo trascorso dall’inserimento in coda anziché al numero, usa RetryFor. Un semplice argomento posizionale è un numero di secondi, e puoi anche passare minutes e hours come argomenti con nome.
Le seguenti dichiarazioni indicano rispettivamente secondi, minuti e ore.
RetryFor registra la scadenza dei retry nel payload del job. Il worker non avvia nuovi tentativi di un job oltre quella scadenza. Se il job ha un metodo retryUntil() o una proprietà retryUntil, questa ha la precedenza su RetryFor. Inoltre, nei job in cui retryUntil è attivo, la scadenza temporale ha la precedenza su Tries.
retryUntil() è adatto quando la scadenza dipende dal contenuto del job, come l’orario previsto di ripristino di un servizio esterno o una scadenza di business.

Limitare le eccezioni non gestite

A volte vuoi continuare a consentire le chiamate manuali a release() e i rilasci durante l’attesa di un lock, ma fallire presto quando le eccezioni non gestite si ripetono. In questo caso specifica Tries e MaxExceptions separatamente.
In questo esempio il job può essere tentato fino a 25 volte. Tuttavia, dopo 3 eccezioni non gestite fallisce anche se non ha raggiunto il limite di tentativi. MaxExceptions non conta i retry causati da release(). Per impostazione predefinita, i tentativi in cui il processo si è bloccato (ad esempio per memoria insufficiente) non contano come eccezioni per MaxExceptions. Se anche i crash devono contare come eccezioni, aggiungi CountCrashesAsExceptions.

Impostare l’intervallo tra i retry

Un job che lancia un’eccezione viene normalmente rilasciato di nuovo nella coda. Puoi impostare l’attesa prima del tentativo successivo con l’attributo Backoff o con il metodo backoff().

Intervallo fisso

Passando un array puoi usare un intervallo diverso per ogni tentativo. Esauriti gli elementi, viene usato l’ultimo valore.
Per variare l’intervallo in base alle condizioni, usa backoff(). backoff() ha la precedenza sull’attributo Backoff.
Se il job non specifica nulla, viene usato --backoff del worker.

Rilasciare i job in attesa con lo stesso backoff

Per eseguire di nuovo un job più tardi senza lanciare un’eccezione, ad esempio quando un’API esterna risponde “in elaborazione”, usa releaseUsingBackoff(). Il job viene rilasciato con il valore dell’array di backoff del job che corrisponde al tentativo corrente. Esauriti i valori viene usato l’ultimo, e senza backoff il job viene rilasciato immediatamente.
Il rilascio automatico in caso di eccezione e il rilascio manuale con releaseUsingBackoff() hanno scopi diversi.
  • In caso di eccezione: il job non è stato elaborato, quindi Laravel lo rilascia usando il backoff.
  • Rilascio manuale: l’elaborazione in sé è corretta, ma il job viene rieseguito più tardi, quando lo stato esterno cambia.
L’attesa di releaseUsingBackoff() deriva da Backoff o backoff() del job. Per indicare esplicitamente un’attesa diversa in un rilascio manuale, usa release(secondi).

Esempio combinato

Il job seguente viene ritentato al massimo per un’ora e tollera fino a 3 eccezioni non gestite. In caso di eccezione e nei rilasci manuali durante l’attesa del pagamento, usa intervalli di 10, 30 e 60 secondi.
Quando è presente RetryFor, il worker usa la scadenza anziché Tries(25) come limite normale dei tentativi. Se specifichi entrambi, decidi se la regola principale è la scadenza temporale o il limite sul numero, e fissa questa intenzione con dei test. MaxExceptions si applica indipendentemente da entrambi.

Precedenza delle impostazioni

Quando mescoli impostazioni del job e del worker, il seguente ordine di precedenza facilita le decisioni. Quando esiste una scadenza da retryUntil o RetryFor, il worker la privilegia rispetto al numero di tries. Se usi insieme RetryFor e retryUntil(), prevale il retryUntil() dinamico.

Come scegliere

  • Se la scadenza per attendere il ripristino di un servizio esterno è chiara, usa RetryFor. Se la scadenza viene decisa a runtime, usa retryUntil().
  • Per i rate limit delle API e il controllo dello stato dei pagamenti, usa Backoff e releaseUsingBackoff().
  • Per tollerare molte attese temporanee di lock ma poche eccezioni reali, combina Tries e MaxExceptions.
  • Nelle elaborazioni in cui i retry accumulano effetti collaterali, progetta non solo il numero di tentativi ma anche l’idempotenza e il controllo dei duplicati lato API esterna.
Puoi specificare Tries e RetryFor anche su listener di eventi e notifiche in coda. Verifica che il payload della destinazione che usi abbia lo stesso contratto di retry.
Ultima modifica il 16 novembre 2026