Zum Hauptinhalt springen
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.
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.

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.
Wenn Sie die Obergrenze aus Laufzeitbedingungen ableiten, verwenden Sie die Methode tries(). Diese Methode hat Vorrang vor dem Attribut Tries.

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.
Die folgenden Angaben stehen jeweils für Sekunden, Minuten und Stunden.
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.
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.
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.

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

Mit einem Array legen Sie für jeden Versuch einen anderen Abstand fest. Sind alle Elemente verbraucht, wird der letzte Wert verwendet.
Um den Abstand abhängig von Bedingungen zu ändern, verwenden Sie backoff(). backoff() hat Vorrang vor dem Attribut Backoff.
Ohne Angabe am Job wird --backoff des Workers verwendet.

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

  • 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.
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.
Zuletzt geändert am 16. November 2026