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

# Políticas de reintento de jobs en cola

> Combina Tries, RetryFor, MaxExceptions y Backoff para diseñar cuándo, cuántas veces y con qué intervalo se reintentan los jobs en cola de Laravel 13.

Al diseñar los reintentos de un job en cola, piensa por separado en cuatro preguntas: cuántas veces intentar, hasta cuándo intentar, cuántas excepciones tolerar y cuántos segundos esperar antes del siguiente intento. En Laravel 13 puedes declarar cada una con atributos y métodos del job.

> [!NOTE]
>
> Esta página se refiere a Laravel 13 y Framework `v13.42.0`. No trata el uso básico de las colas, sino cómo se combinan los ajustes de reintento y cuál tiene prioridad.

| Qué decidir | Atributo / método | Uso principal |
| - | - | - |
| Número máximo de intentos | `#[Tries]` / `tries()` | Limitar el número de intentos |
| Plazo de reintento | `#[RetryFor]` / `retryUntil()` | Intentar solo dentro de una ventana de tiempo tras el envío |
| Límite de excepciones no controladas | `#[MaxExceptions]` | Fallar tras un número determinado de excepciones |
| Intervalo de reintento | `#[Backoff]` / `backoff()` | Definir la espera tras una excepción o una liberación manual |

## Separar el número de intentos del plazo de reintento

En Laravel, un "intento" no es solo una llamada correcta a `handle()`. Las excepciones no controladas, `release()`, las liberaciones por middleware como `WithoutOverlapping` o `RateLimited` y los timeouts también consumen intentos. Si no especificas nada, el worker intenta el job una sola vez.

### `Tries`: limitar el número de intentos

Puedes declarar un límite por job con el atributo `Tries`. El ajuste del job tiene prioridad sobre `--tries` del worker.

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

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

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

Para decidir el límite según condiciones en tiempo de ejecución, usa el método `tries()`. Este método tiene prioridad sobre el atributo `Tries`.

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

### `RetryFor`: definir una ventana de tiempo

Para limitar los reintentos por el tiempo transcurrido desde que el job entró en la cola, en lugar de por número, usa `RetryFor`. Un argumento posicional simple es un número de segundos, y también puedes pasar `minutes` y `hours` como argumentos con nombre.

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

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

Las siguientes declaraciones expresan segundos, minutos y horas respectivamente.

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

`RetryFor` registra el plazo de reintento en el payload del job. El worker no inicia nuevos intentos de un job cuyo plazo ha vencido. Si el job tiene un método `retryUntil()` o una propiedad `retryUntil`, esta tiene prioridad sobre `RetryFor`. Además, en los jobs donde `retryUntil` está activo, el plazo temporal tiene prioridad sobre `Tries`.

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

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

`retryUntil()` es adecuado cuando el plazo depende del propio job, como la hora prevista de recuperación de un servicio externo o una fecha límite de negocio.

## Limitar las excepciones no controladas

A veces quieres seguir permitiendo llamadas manuales a `release()` y liberaciones mientras se espera un lock, pero fallar pronto si se repiten las excepciones no controladas. En ese caso, especifica `Tries` y `MaxExceptions` por separado.

```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
    {
        // Se permiten reintentos mediante release(),
        // pero falla tras 3 excepciones no controladas.
    }
}
```

En este ejemplo, el job puede intentarse hasta 25 veces. Sin embargo, tras 3 excepciones no controladas falla aunque no haya alcanzado el límite de intentos. `MaxExceptions` no cuenta los reintentos causados por `release()`.

Por defecto, los intentos en los que el proceso se bloqueó (por ejemplo, por falta de memoria) no cuentan como excepciones para `MaxExceptions`. Si los bloqueos también deben contar como excepciones, añade `CountCrashesAsExceptions`.

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

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

## Definir el intervalo de reintento

Un job que lanza una excepción normalmente se libera de nuevo en la cola. Puedes definir la espera hasta el siguiente intento con el atributo `Backoff` o el método `backoff()`.

### Intervalo fijo

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

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Tras una excepción no controlada, espera 10 segundos y reintenta.
}
```

Si pasas un array, puedes usar un intervalo distinto en cada intento. Cuando se agotan los elementos, se usa el último valor.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // Espera 10 segundos hasta el 1.er reintento, 30 hasta el 2.º
    // y 60 a partir del 3.º.
}
```

Para cambiar el intervalo según las condiciones, usa `backoff()`. `backoff()` tiene prioridad sobre el atributo `Backoff`.

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

Si el job no especifica nada, se usa `--backoff` del worker.

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

## Liberar jobs en espera con el mismo backoff

Para volver a ejecutar un job más tarde sin lanzar una excepción, por ejemplo cuando una API externa responde que el proceso sigue en curso, usa `releaseUsingBackoff()`. Libera el job con el valor del array de backoff del job que corresponde al intento actual. Cuando se agotan los valores se usa el último, y si no hay backoff el job se libera inmediatamente.

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

        // Procesamiento tras completarse el pago
    }

    private function paymentIsPending(): bool
    {
        // Comprueba el estado del servicio de pagos.
        return true;
    }
}
```

La liberación automática por excepción y la liberación manual con `releaseUsingBackoff()` tienen propósitos distintos.

* **Por excepción**: el job no se pudo procesar, así que Laravel lo libera usando el backoff.
* **Liberación manual**: el procesamiento en sí es correcto, pero el job se vuelve a ejecutar más tarde cuando cambie el estado externo.

La espera de `releaseUsingBackoff()` se toma del `Backoff` o `backoff()` del job. Para indicar explícitamente otra espera en una liberación manual, usa `release(segundos)`.

## Ejemplo combinado

El siguiente job se reintenta como máximo durante una hora y tolera hasta 3 excepciones no controladas. En las excepciones y en las liberaciones manuales mientras espera el pago, usa intervalos de 10, 30 y 60 segundos.

```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
    {
        // Llama al servicio externo para procesar la factura.
    }
}
```

Cuando existe `RetryFor`, el worker usa el plazo en lugar de `Tries(25)` como límite normal de intentos. Si especificas ambos, decide **si la regla principal es el plazo temporal o el límite por número**, y fija esa intención con tests. `MaxExceptions` se aplica de forma independiente de ambos.

## Prioridad de los ajustes

Cuando mezclas ajustes del job y del worker, el siguiente orden de prioridad facilita las decisiones.

| Ámbito | Ajuste prioritario | Alternativa |
| - | - | - |
| Número máximo de intentos | `tries()` | `#[Tries]`, `queue:work --tries` |
| Plazo de reintento | Método / propiedad `retryUntil` | `#[RetryFor]` |
| Límite de excepciones no controladas | `#[MaxExceptions]` | Sin límite si no se especifica |
| Backoff tras una excepción | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Espera de una liberación manual | Ajuste del job mediante `releaseUsingBackoff()` | `release(segundos)` |

Cuando existe un plazo por `retryUntil` o `RetryFor`, el worker lo prioriza sobre el número de `tries`. Si usas `RetryFor` y `retryUntil()` a la vez, prevalece el `retryUntil()` dinámico.

## Cómo elegir

```mermaid theme={null}
flowchart TD
    A["Decidir las condiciones de reintento"] --> B{"¿Detener por número?"}
    B -->|Sí| C["#[Tries]"]
    B -->|No| D["#[RetryFor] o retryUntil()"]
    C --> E{"¿Fallar pronto solo con excepciones no controladas?"}
    D --> E
    E -->|Sí| F["#[MaxExceptions]"]
    E -->|No| G["No es necesario"]
    F --> H{"¿Cambiar el tiempo de espera?"}
    G --> H
    H -->|Sí| I["#[Backoff] / backoff()"]
    H -->|Esperar un estado| J["releaseUsingBackoff()"]
    H -->|No| K["Valores por defecto del worker"]
```

* Si el plazo para esperar la recuperación de un servicio externo está claro, usa `RetryFor`. Si el plazo se decide en tiempo de ejecución, usa `retryUntil()`.
* Para los límites de tasa de una API o la comprobación del estado de un pago, usa `Backoff` y `releaseUsingBackoff()`.
* Para tolerar muchas esperas temporales de lock pero pocas excepciones reales, combina `Tries` y `MaxExceptions`.
* En procesos donde los reintentos acumulan efectos secundarios, diseña no solo el número de intentos, sino también la idempotencia y el control de duplicados en la API externa.

> [!NOTE]
>
> También puedes especificar `Tries` y `RetryFor` en listeners de eventos y notificaciones en cola. Comprueba que el payload del destino que uses tenga el mismo contrato de reintento.

## Enlaces de referencia

* [Documentación oficial de Laravel: Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Documentación oficial de Laravel: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Documentación oficial de Laravel: Liberación manual y `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Documentación oficial de Laravel: Backoff de jobs fallidos](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [Atributo `RetryFor`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [Atributos `Backoff`, `Tries` y `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

- [Control de ejecución de jobs de cola](https://kawax.biz/es/advanced/queue-job-control.md)
- [Colas y jobs](https://kawax.biz/es/queues.md)
- [Actualización de Laravel — Septiembre de 2026](https://kawax.biz/es/blog/changelog/202609.md)
- [Jobs en cola de paquetes y compatibilidad al actualizar](https://kawax.biz/es/advanced/package-queue-jobs.md)
- [Actualización de Laravel — Junio de 2026](https://kawax.biz/es/blog/changelog/202606.md)


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