Skip to main content
When you design retries for a queue job, think about four separate questions: how many times to try, until when to try, how many exceptions to tolerate, and how many seconds to wait before the next attempt. In Laravel 13 you can declare each of these with job attributes and methods.
This page targets Laravel 13 and Framework v13.42.0. It covers how retry settings combine and which one takes precedence, not basic queue usage.

Separate attempt counts from retry deadlines

In Laravel, an “attempt” is not only a successful call to handle(). Unhandled exceptions, release(), releases by middleware such as WithoutOverlapping or RateLimited, and timeouts also consume attempts. If you specify nothing, the worker tries the job only once.

Tries: cap the number of attempts

You can declare a per-job limit with the Tries attribute. The job’s setting takes precedence over the worker’s --tries.
To decide the limit from runtime conditions, use the tries() method. This method takes precedence over the Tries attribute.

RetryFor: set a time window

To limit retries by the time since the job was queued rather than by count, use RetryFor. A bare positional argument is a number of seconds, and you can also pass minutes and hours as named arguments.
The following declarations express seconds, minutes and hours respectively.
RetryFor records the retry deadline in the job payload. The worker does not start new attempts of a job past that deadline. If the job has a retryUntil() method or a retryUntil property, it takes precedence over RetryFor. For a job where retryUntil is in effect, the time-based deadline also takes precedence over Tries.
retryUntil() suits cases where the deadline depends on the job itself, such as when an external service is expected to recover or a business cutoff.

Limit unhandled exceptions

Sometimes you want to keep allowing manual release() calls and releases while waiting for a lock, but fail quickly when unhandled exceptions keep happening. In that case, specify Tries and MaxExceptions separately.
In this example the job can be attempted up to 25 times. However, after 3 unhandled exceptions it fails even if it has not reached the attempt limit. MaxExceptions does not count retries caused by release(). By default, attempts where the process crashed (for example from running out of memory) do not count toward the MaxExceptions exception count. If crashes should also count as exceptions, add CountCrashesAsExceptions.

Set the retry interval

A job that throws an exception is normally released back onto the queue. You can set the wait before the next attempt with the Backoff attribute or the backoff() method.

Fixed interval

Pass an array to use a different interval for each attempt. Once the array is exhausted, the last value is used.
To vary the interval by condition, use backoff(). backoff() takes precedence over the Backoff attribute.
When the job specifies nothing, the worker’s --backoff is used.

Release waiting jobs with the same backoff

To run a job again later without throwing an exception, for example when an external API reports that processing is still in progress, use releaseUsingBackoff(). It releases the job using the value from the job’s backoff array that matches the current attempt. Once the values are exhausted, the last value is used, and without a backoff the job is released immediately.
Automatic release on exception and manual release with releaseUsingBackoff() serve different purposes.
  • On exception: the job could not be processed, so Laravel releases it using the backoff.
  • Manual release: processing itself is fine, but the job runs again later once the external state changes.
The wait for releaseUsingBackoff() comes from the job’s Backoff or backoff(). To set a different wait explicitly for a manual release, use release(seconds).

Combined example

The following job retries for at most one hour and tolerates up to 3 unhandled exceptions. On exceptions and on manual releases while waiting for payment, it uses intervals of 10, 30 and 60 seconds.
When RetryFor is present, the worker uses the deadline rather than Tries(25) as the normal attempt limit. If you specify both, decide whether the time-based deadline or the count-based limit is the primary rule, and lock that intent in with tests. MaxExceptions applies separately from either one.

Precedence of settings

When you mix job and worker settings, the following precedence makes decisions easier. When a deadline from retryUntil or RetryFor exists, the worker gives it precedence over the tries count. When you use RetryFor and retryUntil() together, the dynamic retryUntil() wins.

How to choose

  • If the deadline for waiting on an external service to recover is clear, use RetryFor. If the deadline is decided at runtime, use retryUntil().
  • For API rate limits and payment status checks, use Backoff and releaseUsingBackoff().
  • To tolerate many temporary lock waits but few real exceptions, combine Tries and MaxExceptions.
  • For work where retries repeat side effects, design idempotency and duplicate control on the external API side, not just the attempt count.
You can also specify Tries and RetryFor on queued event listeners and notifications. Check that the payload of the target you use carries the same retry contract.
Last modified on November 16, 2026