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

# Retry-Richtlinien für Queue-Jobs

> Kombinieren Sie Tries, RetryFor, MaxExceptions und Backoff, um festzulegen, wann, wie oft und in welchem Abstand Queue-Jobs in Laravel 13 erneut versucht werden.

Wenn Sie Wiederholungsversuche für einen Queue-Job planen, betrachten Sie vier Fragen getrennt: wie oft versucht wird, bis wann versucht wird, wie viele Exceptions toleriert werden und wie viele Sekunden bis zum nächsten Versuch gewartet wird. In Laravel 13 können Sie all das mit Attributen und Methoden des Jobs deklarieren.

> [!NOTE]
>
> Diese Seite bezieht sich auf Laravel 13 und Framework `v13.42.0`. Sie behandelt nicht die grundlegende Verwendung von Queues, sondern wie sich Retry-Einstellungen kombinieren und welche Vorrang hat.

| Was festzulegen ist | Attribut / Methode | Hauptzweck |
| - | - | - |
| Maximale Anzahl Versuche | `#[Tries]` / `tries()` | Anzahl der Versuche begrenzen |
| Frist für Wiederholungen | `#[RetryFor]` / `retryUntil()` | Nur innerhalb eines Zeitfensters nach dem Dispatch versuchen |
| Obergrenze für unbehandelte Exceptions | `#[MaxExceptions]` | Nach einer bestimmten Anzahl Exceptions fehlschlagen |
| Abstand zwischen Versuchen | `#[Backoff]` / `backoff()` | Wartezeit nach einer Exception oder einer manuellen Freigabe festlegen |

## Anzahl der Versuche und Frist trennen

Ein „Versuch“ in Laravel ist nicht nur ein erfolgreicher Aufruf von `handle()`. Auch unbehandelte Exceptions, `release()`, Freigaben durch Middleware wie `WithoutOverlapping` oder `RateLimited` sowie Timeouts verbrauchen Versuche. Ohne Angabe versucht der Worker den Job nur einmal.

### `Tries`: Anzahl der Versuche begrenzen

Eine Obergrenze pro Job deklarieren Sie mit dem Attribut `Tries`. Die Angabe am Job hat Vorrang vor `--tries` des Workers.

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

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

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

Wenn Sie die Obergrenze aus Laufzeitbedingungen ableiten, verwenden Sie die Methode `tries()`. Diese Methode hat Vorrang vor dem Attribut `Tries`.

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

### `RetryFor`: ein Zeitfenster festlegen

Um Wiederholungen nicht nach Anzahl, sondern nach der Zeit seit dem Einreihen in die Queue zu begrenzen, verwenden Sie `RetryFor`. Ein einfaches Positionsargument ist eine Anzahl Sekunden. Sie können `minutes` und `hours` auch als benannte Argumente angeben.

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

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

Die folgenden Angaben stehen jeweils für Sekunden, Minuten und Stunden.

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

`RetryFor` speichert die Frist im Payload des Jobs. Der Worker startet keine neuen Versuche eines Jobs, dessen Frist abgelaufen ist. Hat der Job eine Methode `retryUntil()` oder eine Eigenschaft `retryUntil`, hat diese Vorrang vor `RetryFor`. Bei Jobs mit wirksamem `retryUntil` hat die zeitbasierte Frist außerdem Vorrang vor `Tries`.

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

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

`retryUntil()` eignet sich, wenn sich die Frist aus dem Inhalt des Jobs ergibt, etwa aus der erwarteten Wiederherstellung eines externen Dienstes oder einem geschäftlichen Stichtag.

## Obergrenze für unbehandelte Exceptions festlegen

Manchmal möchten Sie manuelle `release()`-Aufrufe und Freigaben beim Warten auf einen Lock weiter zulassen, bei wiederholten unbehandelten Exceptions aber schnell fehlschlagen. Geben Sie dann `Tries` und `MaxExceptions` getrennt an.

```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
    {
        // Wiederholungen über release() sind erlaubt,
        // nach 3 unbehandelten Exceptions schlägt der Job fehl.
    }
}
```

In diesem Beispiel kann der Job bis zu 25 Mal versucht werden. Nach 3 unbehandelten Exceptions schlägt er jedoch fehl, auch wenn die Obergrenze der Versuche noch nicht erreicht ist. `MaxExceptions` zählt keine Wiederholungen durch `release()`.

Versuche, bei denen der Prozess abgestürzt ist (etwa wegen Speichermangels), zählen standardmäßig nicht zu den Exceptions für `MaxExceptions`. Wenn auch Abstürze als Exceptions zählen sollen, fügen Sie `CountCrashesAsExceptions` hinzu.

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

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

## Abstand zwischen Versuchen festlegen

Ein Job, der eine Exception wirft, wird normalerweise wieder in die Queue freigegeben. Die Wartezeit bis zum nächsten Versuch legen Sie mit dem Attribut `Backoff` oder der Methode `backoff()` fest.

### Fester Abstand

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

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Nach einer unbehandelten Exception 10 Sekunden warten und erneut versuchen.
}
```

Mit einem Array legen Sie für jeden Versuch einen anderen Abstand fest. Sind alle Elemente verbraucht, wird der letzte Wert verwendet.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // 10 Sekunden bis zum 1. Wiederholungsversuch, 30 bis zum 2.,
    // ab dem 3. jeweils 60 Sekunden warten.
}
```

Um den Abstand abhängig von Bedingungen zu ändern, verwenden Sie `backoff()`. `backoff()` hat Vorrang vor dem Attribut `Backoff`.

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

Ohne Angabe am Job wird `--backoff` des Workers verwendet.

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

## Wartende Jobs mit demselben Backoff freigeben

Wenn Sie einen Job später erneut ausführen möchten, ohne eine Exception zu werfen, etwa weil eine externe API „in Bearbeitung“ meldet, verwenden Sie `releaseUsingBackoff()`. Der Job wird mit dem Wert aus seinem Backoff-Array freigegeben, der zum aktuellen Versuch gehört. Sind die Werte verbraucht, wird der letzte verwendet. Ohne Backoff wird der Job sofort freigegeben.

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

        // Verarbeitung nach abgeschlossener Zahlung
    }

    private function paymentIsPending(): bool
    {
        // Status des Zahlungsdienstes prüfen.
        return true;
    }
}
```

Die automatische Freigabe bei einer Exception und die manuelle Freigabe mit `releaseUsingBackoff()` verfolgen unterschiedliche Zwecke.

* **Bei einer Exception**: Der Job konnte nicht verarbeitet werden, daher gibt Laravel ihn mit dem Backoff frei.
* **Manuelle Freigabe**: Die Verarbeitung selbst ist in Ordnung, der Job läuft aber erst später erneut, wenn sich der externe Zustand geändert hat.

Die Wartezeit von `releaseUsingBackoff()` stammt aus `Backoff` oder `backoff()` des Jobs. Um für eine manuelle Freigabe explizit eine andere Wartezeit anzugeben, verwenden Sie `release(Sekunden)`.

## Kombiniertes Beispiel

Der folgende Job wird höchstens eine Stunde lang wiederholt und toleriert bis zu 3 unbehandelte Exceptions. Bei Exceptions und bei manuellen Freigaben während des Wartens auf die Zahlung verwendet er Abstände von 10, 30 und 60 Sekunden.

```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
    {
        // Externen Dienst aufrufen und die Rechnung verarbeiten.
    }
}
```

Ist `RetryFor` vorhanden, verwendet der Worker die Frist statt `Tries(25)` als normale Obergrenze der Versuche. Wenn Sie beides angeben, entscheiden Sie, **ob die zeitbasierte Frist oder die anzahlbasierte Obergrenze die Hauptregel ist**, und sichern Sie diese Absicht mit Tests ab. `MaxExceptions` gilt unabhängig von beiden.

## Vorrang der Einstellungen

Wenn Sie Job- und Worker-Einstellungen mischen, erleichtert die folgende Rangfolge die Entscheidung.

| Bereich | Vorrangige Einstellung | Fallback |
| - | - | - |
| Maximale Anzahl Versuche | `tries()` | `#[Tries]`, `queue:work --tries` |
| Frist für Wiederholungen | Methode / Eigenschaft `retryUntil` | `#[RetryFor]` |
| Obergrenze für unbehandelte Exceptions | `#[MaxExceptions]` | Ohne Angabe keine Obergrenze |
| Backoff nach einer Exception | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Wartezeit bei manueller Freigabe | Job-Einstellung über `releaseUsingBackoff()` | `release(Sekunden)` |

Gibt es eine Frist durch `retryUntil` oder `RetryFor`, hat sie für den Worker Vorrang vor der Anzahl aus `tries`. Wenn Sie `RetryFor` und `retryUntil()` zusammen verwenden, hat das dynamische `retryUntil()` Vorrang.

## Auswahl

```mermaid theme={null}
flowchart TD
    A["Bedingungen für Wiederholungen festlegen"] --> B{"Nach Anzahl stoppen?"}
    B -->|Ja| C["#[Tries]"]
    B -->|Nein| D["#[RetryFor] oder retryUntil()"]
    C --> E{"Nur bei unbehandelten Exceptions früh fehlschlagen?"}
    D --> E
    E -->|Ja| F["#[MaxExceptions]"]
    E -->|Nein| G["Nicht nötig"]
    F --> H{"Wartezeit ändern?"}
    G --> H
    H -->|Ja| I["#[Backoff] / backoff()"]
    H -->|Auf Zustand warten| J["releaseUsingBackoff()"]
    H -->|Nein| K["Standardwerte des Workers"]
```

* Ist die Frist für das Warten auf die Wiederherstellung eines externen Dienstes klar, verwenden Sie `RetryFor`. Ergibt sich die Frist erst zur Laufzeit, verwenden Sie `retryUntil()`.
* Für API-Rate-Limits und die Prüfung von Zahlungsstatus verwenden Sie `Backoff` und `releaseUsingBackoff()`.
* Um viele vorübergehende Lock-Wartezeiten, aber nur wenige echte Exceptions zuzulassen, kombinieren Sie `Tries` und `MaxExceptions`.
* Bei Verarbeitungen, deren Wiederholung Nebenwirkungen vervielfacht, planen Sie neben der Anzahl der Versuche auch Idempotenz und die Duplikatkontrolle auf Seiten der externen API.

> [!NOTE]
>
> `Tries` und `RetryFor` können Sie auch für Event-Listener und Benachrichtigungen in der Queue angeben. Prüfen Sie, dass der Payload des jeweiligen Ziels denselben Retry-Vertrag trägt.

## Referenz-Links

* [Offizielle Laravel-Dokumentation: Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Offizielle Laravel-Dokumentation: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Offizielle Laravel-Dokumentation: Manuelle Freigabe und `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Offizielle Laravel-Dokumentation: Backoff für fehlgeschlagene Jobs](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)
* [Attribute `Backoff`, `Tries` und `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

- [Queues und Jobs](https://kawax.biz/de/queues.md)
- [Ausführungssteuerung von Queue-Jobs](https://kawax.biz/de/advanced/queue-job-control.md)
- [Queue-Jobs in Paketen und Kompatibilität bei Updates](https://kawax.biz/de/advanced/package-queue-jobs.md)
- [PHP-Attribute für Controller](https://kawax.biz/de/advanced/controller-attributes.md)
- [Übersicht der neuen Features in Laravel 13](https://kawax.biz/de/blog/laravel-13-new-features.md)


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