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 ahandle(). 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.
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.
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 arelease() 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.
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 atributoBackoff o el método backoff().
Intervalo fijo
backoff(). backoff() tiene prioridad sobre el atributo Backoff.
--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, usareleaseUsingBackoff(). 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.
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.
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.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, usaretryUntil(). - Para los límites de tasa de una API o la comprobación del estado de un pago, usa
BackoffyreleaseUsingBackoff(). - Para tolerar muchas esperas temporales de lock pero pocas excepciones reales, combina
TriesyMaxExceptions. - 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
- Documentación oficial de Laravel: Max job attempts and timeout
- Documentación oficial de Laravel: Time-based attempts
- Documentación oficial de Laravel: Liberación manual y
releaseUsingBackoff - Documentación oficial de Laravel: Backoff de jobs fallidos
- Atributo
RetryFor - Atributos
Backoff,TriesyMaxExceptions Queue::getJobExpirationInteractsWithQueue::releaseUsingBackoff