> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Politiche di retry dei job in coda

> Combina Tries, RetryFor, MaxExceptions e Backoff per progettare quando, quante volte e a quale intervallo vengono ritentati i job in coda di Laravel 13.

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.

> [!NOTE]
>
> 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.

| Cosa decidere | Attributo / metodo | Uso principale |
| - | - | - |
| Numero massimo di tentativi | `#[Tries]` / `tries()` | Limitare il numero di tentativi |
| Scadenza dei retry | `#[RetryFor]` / `retryUntil()` | Tentare solo entro una finestra temporale dopo il dispatch |
| Limite di eccezioni non gestite | `#[MaxExceptions]` | Fallire dopo un certo numero di eccezioni |
| Intervallo tra i retry | `#[Backoff]` / `backoff()` | Definire l'attesa dopo un'eccezione o un rilascio manuale |

## 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.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

#[Tries(5)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

Per decidere il limite in base a condizioni a runtime, usa il metodo `tries()`. Questo metodo ha la precedenza sull'attributo `Tries`.

```php theme={null}
public function tries(): int
{
    return $this->invoice->isLarge() ? 10 : 3;
}
```

### `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.

```php theme={null}
use Illuminate\Queue\Attributes\RetryFor;

#[RetryFor(hours: 1)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

Le seguenti dichiarazioni indicano rispettivamente secondi, minuti e ore.

```php theme={null}
#[RetryFor(90)]
#[RetryFor(minutes: 10)]
#[RetryFor(hours: 4)]
#[RetryFor(hours: 1, minutes: 30)]
```

`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`.

```php theme={null}
use DateTime;

public function retryUntil(): DateTime
{
    return now()->plus(minutes: 30);
}
```

`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.

```php theme={null}
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    public function handle(): void
    {
        // I retry tramite release() sono consentiti,
        // ma il job fallisce dopo 3 eccezioni non gestite.
    }
}
```

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`.

```php theme={null}
use Illuminate\Queue\Attributes\CountCrashesAsExceptions;
use Illuminate\Queue\Attributes\MaxExceptions;

#[CountCrashesAsExceptions]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

## 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

```php theme={null}
use Illuminate\Queue\Attributes\Backoff;

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Dopo un'eccezione non gestita, attende 10 secondi e riprova.
}
```

Passando un array puoi usare un intervallo diverso per ogni tentativo. Esauriti gli elementi, viene usato l'ultimo valore.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // Attende 10 secondi prima del 1° retry, 30 prima del 2°
    // e 60 dal 3° in poi.
}
```

Per variare l'intervallo in base alle condizioni, usa `backoff()`. `backoff()` ha la precedenza sull'attributo `Backoff`.

```php theme={null}
public function backoff(): int|array
{
    return $this->invoice->isFromExternalProvider()
        ? [30, 60, 300]
        : [5, 15, 30];
}
```

Se il job non specifica nulla, viene usato `--backoff` del worker.

```shell theme={null}
php artisan queue:work redis --tries=3 --backoff=10
```

## 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.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Backoff;

#[Backoff([10, 30, 60])]
class CheckPaymentStatus implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        if ($this->paymentIsPending()) {
            $this->releaseUsingBackoff();

            return;
        }

        // Elaborazione dopo il completamento del pagamento
    }

    private function paymentIsPending(): bool
    {
        // Controlla lo stato del servizio di pagamento.
        return true;
    }
}
```

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.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\RetryFor;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[RetryFor(hours: 1)]
#[MaxExceptions(3)]
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        // Chiama il servizio esterno per elaborare la fattura.
    }
}
```

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.

| Ambito | Impostazione prioritaria | Fallback |
| - | - | - |
| Numero massimo di tentativi | `tries()` | `#[Tries]`, `queue:work --tries` |
| Scadenza dei retry | Metodo / proprietà `retryUntil` | `#[RetryFor]` |
| Limite di eccezioni non gestite | `#[MaxExceptions]` | Nessun limite se non specificato |
| Backoff dopo un'eccezione | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Attesa di un rilascio manuale | Impostazione del job tramite `releaseUsingBackoff()` | `release(secondi)` |

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

```mermaid theme={null}
flowchart TD
    A["Definire le condizioni di retry"] --> B{"Fermarsi in base al numero?"}
    B -->|Sì| C["#[Tries]"]
    B -->|No| D["#[RetryFor] o retryUntil()"]
    C --> E{"Fallire presto solo per eccezioni non gestite?"}
    D --> E
    E -->|Sì| F["#[MaxExceptions]"]
    E -->|No| G["Non necessario"]
    F --> H{"Cambiare il tempo di attesa?"}
    G --> H
    H -->|Sì| I["#[Backoff] / backoff()"]
    H -->|Attesa di uno stato| J["releaseUsingBackoff()"]
    H -->|No| K["Valori predefiniti del worker"]
```

* 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.

> [!NOTE]
>
> 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.

## Link di riferimento

* [Documentazione ufficiale di Laravel: Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Documentazione ufficiale di Laravel: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Documentazione ufficiale di Laravel: Rilascio manuale e `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Documentazione ufficiale di Laravel: Backoff dei job falliti](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [Attributo `RetryFor`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [Attributi `Backoff`, `Tries` e `MaxExceptions`](https://github.com/laravel/framework/tree/v13.42.0/src/Illuminate/Queue/Attributes)
* [`Queue::getJobExpiration`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Queue.php)
* [`InteractsWithQueue::releaseUsingBackoff`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/InteractsWithQueue.php)


## Related topics

- [Aggiornamenti Laravel di aprile 2026](https://kawax.biz/it/blog/changelog/202604.md)
- [Aggiornamenti Laravel di settembre 2026](https://kawax.biz/it/blog/changelog/202609.md)
- [Job in coda dei pacchetti e compatibilità durante gli aggiornamenti](https://kawax.biz/it/advanced/package-queue-jobs.md)
- [Code e job](https://kawax.biz/it/queues.md)
- [Tecniche pratiche di Laravel Telescope](https://kawax.biz/it/blog/telescope-introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.