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

# Retrybeleid voor queuejobs

> Combineer Tries, RetryFor, MaxExceptions en Backoff om te bepalen wanneer, hoe vaak en met welk interval queuejobs in Laravel 13 opnieuw worden geprobeerd.

Wanneer je retries voor een queuejob ontwerpt, bekijk je vier vragen apart: hoe vaak je het probeert, tot wanneer je het probeert, hoeveel exceptions je toestaat en hoeveel seconden je wacht tot de volgende poging. In Laravel 13 kun je dit allemaal declareren met attributen en methodes op de job.

> [!NOTE]
>
> Deze pagina is gericht op Laravel 13 en Framework `v13.42.0`. Het gaat niet over het basisgebruik van queues, maar over hoe retry-instellingen samenwerken en welke voorrang heeft.

| Wat je bepaalt | Attribuut / methode | Belangrijkste gebruik |
| - | - | - |
| Maximaal aantal pogingen | `#[Tries]` / `tries()` | Het aantal pogingen begrenzen |
| Deadline voor retries | `#[RetryFor]` / `retryUntil()` | Alleen proberen binnen een tijdvenster na het dispatchen |
| Limiet voor onafgehandelde exceptions | `#[MaxExceptions]` | Laten falen na een bepaald aantal exceptions |
| Interval tussen retries | `#[Backoff]` / `backoff()` | De wachttijd na een exception of een handmatige release bepalen |

## Aantal pogingen en retry-deadline scheiden

Een "poging" in Laravel is niet alleen een geslaagde aanroep van `handle()`. Ook onafgehandelde exceptions, `release()`, releases door middleware zoals `WithoutOverlapping` of `RateLimited` en timeouts verbruiken pogingen. Als je niets opgeeft, probeert de worker de job maar één keer.

### `Tries`: het aantal pogingen begrenzen

Je kunt een limiet per job declareren met het attribuut `Tries`. De instelling op de job heeft voorrang op `--tries` van de worker.

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

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

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

Wil je de limiet bepalen op basis van runtime-omstandigheden, gebruik dan de methode `tries()`. Deze methode heeft voorrang op het attribuut `Tries`.

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

### `RetryFor`: een tijdvenster opgeven

Om retries niet op aantal maar op de tijd sinds het in de queue plaatsen te begrenzen, gebruik je `RetryFor`. Een los positioneel argument is een aantal seconden, en je kunt ook `minutes` en `hours` als benoemde argumenten opgeven.

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

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

De volgende declaraties staan respectievelijk voor seconden, minuten en uren.

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

`RetryFor` legt de retry-deadline vast in de payload van de job. De worker start geen nieuwe pogingen meer voor een job waarvan de deadline verstreken is. Heeft de job een methode `retryUntil()` of een property `retryUntil`, dan heeft die voorrang op `RetryFor`. Bij jobs waarvoor `retryUntil` actief is, heeft de tijdgebonden deadline bovendien voorrang op `Tries`.

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

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

`retryUntil()` is geschikt wanneer de deadline van de inhoud van de job afhangt, zoals het verwachte hersteltijdstip van een externe dienst of een zakelijke deadline.

## Een limiet voor onafgehandelde exceptions instellen

Soms wil je handmatige `release()`-aanroepen en releases tijdens het wachten op een lock blijven toestaan, maar snel laten falen als onafgehandelde exceptions zich blijven voordoen. Geef in dat geval `Tries` en `MaxExceptions` apart op.

```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
    {
        // Retries via release() zijn toegestaan,
        // maar na 3 onafgehandelde exceptions faalt de job.
    }
}
```

In dit voorbeeld kan de job tot 25 keer worden geprobeerd. Na 3 onafgehandelde exceptions faalt hij echter, ook als de limiet van pogingen nog niet bereikt is. `MaxExceptions` telt geen retries die door `release()` ontstaan.

Pogingen waarbij het proces crashte (bijvoorbeeld door geheugentekort) tellen standaard niet mee voor het aantal exceptions van `MaxExceptions`. Moeten crashes ook als exceptions tellen, voeg dan `CountCrashesAsExceptions` toe.

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

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

## Het interval tussen retries instellen

Een job die een exception gooit, wordt normaal gesproken opnieuw in de queue vrijgegeven. De wachttijd tot de volgende poging stel je in met het attribuut `Backoff` of de methode `backoff()`.

### Vast interval

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

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Na een onafgehandelde exception 10 seconden wachten en opnieuw proberen.
}
```

Met een array stel je per poging een ander interval in. Zijn alle elementen gebruikt, dan wordt de laatste waarde gebruikt.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // 10 seconden tot de 1e retry, 30 tot de 2e,
    // en vanaf de 3e telkens 60 seconden wachten.
}
```

Wil je het interval laten afhangen van omstandigheden, gebruik dan `backoff()`. `backoff()` heeft voorrang op het attribuut `Backoff`.

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

Als de job niets opgeeft, wordt `--backoff` van de worker gebruikt.

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

## Wachtende jobs vrijgeven met dezelfde backoff

Wil je een job later opnieuw uitvoeren zonder een exception te gooien, bijvoorbeeld omdat een externe API "in behandeling" teruggeeft, gebruik dan `releaseUsingBackoff()`. De job wordt vrijgegeven met de waarde uit zijn backoff-array die bij de huidige poging hoort. Zijn de waarden op, dan wordt de laatste gebruikt, en zonder backoff wordt de job direct vrijgegeven.

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

        // Verwerking na afronding van de betaling
    }

    private function paymentIsPending(): bool
    {
        // Controleer de status van de betaaldienst.
        return true;
    }
}
```

Automatisch vrijgeven bij een exception en handmatig vrijgeven met `releaseUsingBackoff()` hebben verschillende doelen.

* **Bij een exception**: de job kon niet worden verwerkt, dus Laravel geeft hem vrij met de backoff.
* **Handmatig vrijgeven**: de verwerking zelf is in orde, maar de job wordt later opnieuw uitgevoerd zodra de externe status verandert.

De wachttijd van `releaseUsingBackoff()` komt uit `Backoff` of `backoff()` van de job. Wil je bij een handmatige release expliciet een andere wachttijd opgeven, gebruik dan `release(seconden)`.

## Gecombineerd voorbeeld

De volgende job wordt maximaal een uur lang opnieuw geprobeerd en staat tot 3 onafgehandelde exceptions toe. Bij exceptions en bij handmatige releases tijdens het wachten op de betaling gebruikt hij intervallen van 10, 30 en 60 seconden.

```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
    {
        // Roep de externe dienst aan om de factuur te verwerken.
    }
}
```

Als `RetryFor` aanwezig is, gebruikt de worker de deadline in plaats van `Tries(25)` als normale limiet voor pogingen. Geef je beide op, bepaal dan **of de tijdgebonden deadline of de limiet op aantal de hoofdregel is**, en leg die bedoeling vast met tests. `MaxExceptions` geldt los van beide.

## Voorrang van instellingen

Wanneer je instellingen van de job en de worker combineert, maakt de volgende volgorde het beslissen eenvoudiger.

| Onderwerp | Instelling met voorrang | Fallback |
| - | - | - |
| Maximaal aantal pogingen | `tries()` | `#[Tries]`, `queue:work --tries` |
| Deadline voor retries | Methode / property `retryUntil` | `#[RetryFor]` |
| Limiet voor onafgehandelde exceptions | `#[MaxExceptions]` | Geen limiet als niet opgegeven |
| Backoff na een exception | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Wachttijd bij handmatige release | Jobinstelling via `releaseUsingBackoff()` | `release(seconden)` |

Bestaat er een deadline via `retryUntil` of `RetryFor`, dan geeft de worker die voorrang op het aantal uit `tries`. Gebruik je `RetryFor` en `retryUntil()` samen, dan wint de dynamische `retryUntil()`.

## Hoe je kiest

```mermaid theme={null}
flowchart TD
    A["Retryvoorwaarden bepalen"] --> B{"Stoppen op aantal?"}
    B -->|Ja| C["#[Tries]"]
    B -->|Nee| D["#[RetryFor] of retryUntil()"]
    C --> E{"Alleen bij onafgehandelde exceptions vroeg falen?"}
    D --> E
    E -->|Ja| F["#[MaxExceptions]"]
    E -->|Nee| G["Niet nodig"]
    F --> H{"Wachttijd aanpassen?"}
    G --> H
    H -->|Ja| I["#[Backoff] / backoff()"]
    H -->|Wachten op status| J["releaseUsingBackoff()"]
    H -->|Nee| K["Standaardwaarden van de worker"]
```

* Is de deadline voor het wachten op herstel van een externe dienst duidelijk, gebruik dan `RetryFor`. Wordt de deadline pas tijdens runtime bepaald, gebruik dan `retryUntil()`.
* Voor API-rate-limits en het controleren van betaalstatussen gebruik je `Backoff` en `releaseUsingBackoff()`.
* Wil je veel tijdelijke lock-wachttijden maar weinig echte exceptions toestaan, combineer dan `Tries` en `MaxExceptions`.
* Bij verwerkingen waarbij retries neveneffecten opstapelen, ontwerp je naast het aantal pogingen ook idempotentie en duplicaatcontrole aan de kant van de externe API.

> [!NOTE]
>
> Je kunt `Tries` en `RetryFor` ook opgeven voor eventlisteners en notificaties in de queue. Controleer dat de payload van het doel dat je gebruikt hetzelfde retrycontract heeft.

## Referenties

* [Officiële Laravel-documentatie: Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Officiële Laravel-documentatie: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Officiële Laravel-documentatie: Handmatig vrijgeven en `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Officiële Laravel-documentatie: Backoff voor mislukte jobs](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [Attribuut `RetryFor`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [Attributen `Backoff`, `Tries` en `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

- [Praktische technieken voor Laravel Telescope](https://kawax.biz/nl/blog/telescope-introduction.md)
- [Praktische use-cases voor Laravel Pennant](https://kawax.biz/nl/blog/laravel-pennant.md)
- [Queue-jobs in packages en compatibiliteit bij updates](https://kawax.biz/nl/advanced/package-queue-jobs.md)
- [Laravel Doctor — een diagnosetool voor applicaties](https://kawax.biz/nl/blog/laravel-doctor-introduction.md)
- [Uitvoeringscontrole van queue-jobs](https://kawax.biz/nl/advanced/queue-job-control.md)


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