Saltar al contenido principal
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.
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.

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

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.
Las siguientes declaraciones expresan segundos, minutos y horas respectivamente.
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.
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.
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.

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

Si pasas un array, puedes usar un intervalo distinto en cada intento. Cuando se agotan los elementos, se usa el último valor.
Para cambiar el intervalo según las condiciones, usa backoff(). backoff() tiene prioridad sobre el atributo Backoff.
Si el job no especifica nada, se usa --backoff del worker.

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

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

Última modificación el 16 de noviembre de 2026