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

# Politiques de nouvelle tentative des jobs en file

> Combinez Tries, RetryFor, MaxExceptions et Backoff pour définir quand, combien de fois et à quel intervalle les jobs en file de Laravel 13 sont relancés.

Lorsque vous concevez les nouvelles tentatives d'un job en file, traitez séparément quatre questions : combien de fois essayer, jusqu'à quand essayer, combien d'exceptions tolérer et combien de secondes attendre avant la tentative suivante. Dans Laravel 13, vous pouvez déclarer chacune d'elles avec des attributs et des méthodes du job.

> [!NOTE]
>
> Cette page porte sur Laravel 13 et Framework `v13.42.0`. Elle ne traite pas de l'utilisation de base des files, mais de la combinaison des paramètres de nouvelle tentative et de leur ordre de priorité.

| Ce qu'il faut décider | Attribut / méthode | Usage principal |
| - | - | - |
| Nombre maximal de tentatives | `#[Tries]` / `tries()` | Plafonner le nombre de tentatives |
| Échéance des nouvelles tentatives | `#[RetryFor]` / `retryUntil()` | N'essayer que dans une fenêtre de temps après l'envoi |
| Limite d'exceptions non gérées | `#[MaxExceptions]` | Échouer après un certain nombre d'exceptions |
| Intervalle entre tentatives | `#[Backoff]` / `backoff()` | Définir l'attente après une exception ou une libération manuelle |

## Séparer le nombre de tentatives de l'échéance

Dans Laravel, une « tentative » n'est pas seulement un appel réussi à `handle()`. Les exceptions non gérées, `release()`, les libérations par un middleware comme `WithoutOverlapping` ou `RateLimited` et les timeouts consomment aussi des tentatives. Si vous ne précisez rien, le worker n'essaie le job qu'une seule fois.

### `Tries` : plafonner le nombre de tentatives

Vous pouvez déclarer une limite par job avec l'attribut `Tries`. Le paramètre du job prime sur l'option `--tries` du worker.

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

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

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

Pour déterminer la limite à partir de conditions à l'exécution, utilisez la méthode `tries()`. Cette méthode prime sur l'attribut `Tries`.

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

### `RetryFor` : définir une fenêtre de temps

Pour limiter les nouvelles tentatives par le temps écoulé depuis la mise en file plutôt que par leur nombre, utilisez `RetryFor`. Un argument positionnel simple est un nombre de secondes, et vous pouvez aussi passer `minutes` et `hours` en arguments nommés.

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

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

Les déclarations suivantes expriment respectivement des secondes, des minutes et des heures.

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

`RetryFor` enregistre l'échéance dans le payload du job. Le worker ne lance pas de nouvelle tentative d'un job dont l'échéance est dépassée. Si le job possède une méthode `retryUntil()` ou une propriété `retryUntil`, celle-ci prime sur `RetryFor`. De plus, pour un job où `retryUntil` est actif, l'échéance temporelle prime sur `Tries`.

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

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

`retryUntil()` convient lorsque l'échéance dépend du contenu du job, comme l'heure de rétablissement prévue d'un service externe ou une date butoir métier.

## Limiter les exceptions non gérées

Vous pouvez vouloir continuer à autoriser les appels manuels à `release()` et les libérations pendant l'attente d'un verrou, tout en échouant rapidement quand les exceptions non gérées se répètent. Dans ce cas, précisez `Tries` et `MaxExceptions` séparément.

```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
    {
        // Les nouvelles tentatives via release() sont autorisées,
        // mais le job échoue après 3 exceptions non gérées.
    }
}
```

Dans cet exemple, le job peut être tenté jusqu'à 25 fois. Cependant, après 3 exceptions non gérées, il échoue même si la limite de tentatives n'est pas atteinte. `MaxExceptions` ne compte pas les nouvelles tentatives dues à `release()`.

Par défaut, les tentatives où le processus a planté (par exemple faute de mémoire) ne comptent pas comme exceptions pour `MaxExceptions`. Si les plantages doivent aussi compter comme exceptions, ajoutez `CountCrashesAsExceptions`.

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

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

## Définir l'intervalle entre tentatives

Un job qui lève une exception est normalement libéré à nouveau dans la file. Vous pouvez définir l'attente avant la tentative suivante avec l'attribut `Backoff` ou la méthode `backoff()`.

### Intervalle fixe

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

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Après une exception non gérée, attendre 10 secondes puis réessayer.
}
```

Avec un tableau, vous pouvez utiliser un intervalle différent à chaque tentative. Une fois les éléments épuisés, la dernière valeur est utilisée.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // Attendre 10 secondes avant la 1re nouvelle tentative, 30 avant la 2e,
    // puis 60 à partir de la 3e.
}
```

Pour faire varier l'intervalle selon les conditions, utilisez `backoff()`. `backoff()` prime sur l'attribut `Backoff`.

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

Si le job ne précise rien, l'option `--backoff` du worker est utilisée.

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

## Libérer les jobs en attente avec le même backoff

Pour relancer un job plus tard sans lever d'exception, par exemple lorsqu'une API externe répond « en cours de traitement », utilisez `releaseUsingBackoff()`. Le job est libéré avec la valeur du tableau de backoff du job qui correspond à la tentative en cours. Une fois les valeurs épuisées, la dernière est utilisée, et sans backoff le job est libéré immédiatement.

```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;
        }

        // Traitement après la finalisation du paiement
    }

    private function paymentIsPending(): bool
    {
        // Vérifier l'état du service de paiement.
        return true;
    }
}
```

La libération automatique sur exception et la libération manuelle avec `releaseUsingBackoff()` ont des objectifs différents.

* **Sur exception** : le job n'a pas pu être traité, Laravel le libère donc en utilisant le backoff.
* **Libération manuelle** : le traitement lui-même est correct, mais le job est relancé plus tard, une fois l'état externe modifié.

L'attente de `releaseUsingBackoff()` provient du `Backoff` ou du `backoff()` du job. Pour indiquer explicitement une autre attente lors d'une libération manuelle, utilisez `release(secondes)`.

## Exemple combiné

Le job suivant est relancé pendant une heure au maximum et tolère jusqu'à 3 exceptions non gérées. En cas d'exception et lors des libérations manuelles en attente du paiement, il utilise des intervalles de 10, 30 et 60 secondes.

```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
    {
        // Appeler le service externe pour traiter la facture.
    }
}
```

Lorsque `RetryFor` est présent, le worker utilise l'échéance plutôt que `Tries(25)` comme limite normale de tentatives. Si vous précisez les deux, décidez **si la règle principale est l'échéance temporelle ou la limite en nombre**, et figez cette intention avec des tests. `MaxExceptions` s'applique indépendamment de l'une et de l'autre.

## Ordre de priorité des paramètres

Lorsque vous mélangez des paramètres du job et du worker, l'ordre de priorité suivant facilite les décisions.

| Cible | Paramètre prioritaire | Repli |
| - | - | - |
| Nombre maximal de tentatives | `tries()` | `#[Tries]`, `queue:work --tries` |
| Échéance des nouvelles tentatives | Méthode / propriété `retryUntil` | `#[RetryFor]` |
| Limite d'exceptions non gérées | `#[MaxExceptions]` | Aucune limite si non précisé |
| Backoff après une exception | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Attente d'une libération manuelle | Paramètre du job via `releaseUsingBackoff()` | `release(secondes)` |

Lorsqu'une échéance définie par `retryUntil` ou `RetryFor` existe, le worker la fait primer sur le nombre de `tries`. Si vous utilisez `RetryFor` et `retryUntil()` ensemble, c'est le `retryUntil()` dynamique qui l'emporte.

## Comment choisir

```mermaid theme={null}
flowchart TD
    A["Définir les conditions de nouvelle tentative"] --> B{"Arrêter selon le nombre ?"}
    B -->|Oui| C["#[Tries]"]
    B -->|Non| D["#[RetryFor] ou retryUntil()"]
    C --> E{"Échouer tôt uniquement sur exceptions non gérées ?"}
    D --> E
    E -->|Oui| F["#[MaxExceptions]"]
    E -->|Non| G["Inutile"]
    F --> H{"Modifier le temps d'attente ?"}
    G --> H
    H -->|Oui| I["#[Backoff] / backoff()"]
    H -->|Attente d'un état| J["releaseUsingBackoff()"]
    H -->|Non| K["Valeurs par défaut du worker"]
```

* Si l'échéance d'attente du rétablissement d'un service externe est claire, utilisez `RetryFor`. Si elle est déterminée à l'exécution, utilisez `retryUntil()`.
* Pour les limites de débit d'une API ou la vérification de l'état d'un paiement, utilisez `Backoff` et `releaseUsingBackoff()`.
* Pour tolérer de nombreuses attentes temporaires de verrou mais peu d'exceptions réelles, combinez `Tries` et `MaxExceptions`.
* Pour les traitements où les nouvelles tentatives cumulent des effets de bord, concevez non seulement le nombre de tentatives, mais aussi l'idempotence et le contrôle des doublons côté API externe.

> [!NOTE]
>
> Vous pouvez aussi préciser `Tries` et `RetryFor` sur les listeners d'événements et les notifications mis en file. Vérifiez que le payload de la cible utilisée porte le même contrat de nouvelle tentative.

## Liens de référence

* [Documentation officielle de Laravel : Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Documentation officielle de Laravel : Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Documentation officielle de Laravel : Libération manuelle et `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Documentation officielle de Laravel : Backoff des jobs échoués](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [Attribut `RetryFor`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [Attributs `Backoff`, `Tries` et `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

- [Mises à jour Laravel — septembre 2026](https://kawax.biz/fr/blog/changelog/202609.md)
- [Jobs en file d'attente d'un package et compatibilité lors des mises à jour](https://kawax.biz/fr/advanced/package-queue-jobs.md)
- [Contrôle de l'exécution des jobs de queue](https://kawax.biz/fr/advanced/queue-job-control.md)
- [Tester des packages Laravel avec Orchestra Testbench](https://kawax.biz/fr/advanced/package-testing.md)
- [Enregistrement et mise en cache des écouteurs d'événements d'un package](https://kawax.biz/fr/advanced/package-events.md)


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