Naar hoofdinhoud gaan
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.
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.

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.
Wil je de limiet bepalen op basis van runtime-omstandigheden, gebruik dan de methode tries(). Deze methode heeft voorrang op het attribuut Tries.

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.
De volgende declaraties staan respectievelijk voor seconden, minuten en uren.
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.
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.
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.

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

Met een array stel je per poging een ander interval in. Zijn alle elementen gebruikt, dan wordt de laatste waarde gebruikt.
Wil je het interval laten afhangen van omstandigheden, gebruik dan backoff(). backoff() heeft voorrang op het attribuut Backoff.
Als de job niets opgeeft, wordt --backoff van de worker gebruikt.

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

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

Laatst gewijzigd op 16 november 2026