메인 콘텐츠로 건너뛰기
큐 잡의 재시도를 설계할 때는 “몇 번 시도할지”, “언제까지 시도할지”, “예외를 몇 번 허용할지”, “다음 시도까지 몇 초 기다릴지”를 나누어 생각합니다. Laravel 13에서는 이를 잡의 Attribute와 메서드로 선언할 수 있습니다.
이 페이지는 Laravel 13과 Framework v13.42.0을 대상으로 합니다. 기본적인 큐 사용법이 아니라 재시도 설정의 조합과 우선순위를 다룹니다.

시도 횟수와 재시도 기한을 나눈다

Laravel의 “시도”는 handle()이 정상적으로 호출된 횟수만이 아닙니다. 처리되지 않은 예외, release(), WithoutOverlapping이나 RateLimited 같은 미들웨어에 의한 해제, 타임아웃도 시도를 소비합니다. 아무것도 지정하지 않으면 워커는 잡을 한 번만 시도합니다.

Tries: 횟수에 상한을 둔다

잡별 상한을 Tries Attribute로 선언할 수 있습니다. 워커의 --tries보다 잡 쪽의 지정이 우선됩니다.
실행 시의 조건으로 상한을 정하려면 tries() 메서드를 사용합니다. 이 메서드는 Tries Attribute보다 우선됩니다.

RetryFor: 시간 범위를 지정한다

횟수가 아니라 큐에 투입된 뒤 재시도할 수 있는 시간을 지정하려면 RetryFor를 사용합니다. 이름 없는 위치 인수는 초 단위이며, minutes와 hours를 이름 있는 인수로 지정할 수도 있습니다.
다음 지정은 각각 초·분·시간을 나타냅니다.
RetryFor는 잡의 페이로드에 재시도 기한을 기록합니다. 워커는 그 기한이 지난 잡을 새로 실행하지 않습니다. retryUntil() 메서드나 retryUntil 프로퍼티가 있으면 그쪽이 RetryFor보다 우선됩니다. 또한 retryUntil이 유효한 잡에서는 Tries보다 시간에 의한 기한이 우선됩니다.
retryUntil()은 외부 서비스의 복구 시각이나 업무상의 마감처럼 잡의 내용에서 기한을 동적으로 정하는 경우에 적합합니다.

처리되지 않은 예외의 상한을 정한다

수동 release()나 락 획득 대기에 의한 해제는 계속 허용하면서, 처리되지 않은 예외가 계속되면 빨리 실패시키고 싶을 때가 있습니다. 이 경우 Tries와 MaxExceptions를 나누어 지정합니다.
이 예에서 잡은 최대 25번까지 시도할 수 있습니다. 다만 처리되지 않은 예외가 3번 발생하면 시도 횟수 상한에 도달하지 않았더라도 실패합니다. MaxExceptions는 release()에 의한 재시도 횟수를 세기 위한 설정이 아닙니다. 프로세스가 메모리 부족 등으로 크래시한 시도는 기본적으로 MaxExceptions의 예외 수에 포함되지 않습니다. 크래시도 예외로 세어야 한다면 CountCrashesAsExceptions를 추가합니다.

재시도 간격을 설정한다

예외가 발생한 잡은 보통 다시 큐로 해제됩니다. 다음 시도까지의 대기 시간은 Backoff Attribute나 backoff() 메서드로 설정할 수 있습니다.

고정 간격

배열을 지정하면 시도마다 다른 간격을 설정할 수 있습니다. 배열 요소를 다 쓰면 마지막 값이 사용됩니다.
조건에 따라 간격을 바꾸려면 backoff()를 사용합니다. backoff()는 Backoff Attribute보다 우선됩니다.
잡별 지정이 없으면 워커의 --backoff가 사용됩니다.

대기 중인 잡을 같은 백오프로 해제한다

외부 API가 “처리 중”을 반환했을 때처럼 예외를 던지지 않고 잡을 나중에 다시 실행하고 싶다면 releaseUsingBackoff()를 사용합니다. 잡에 설정한 백오프 배열 중 현재 시도에 해당하는 값으로 해제합니다. 값을 다 쓰면 마지막 값이 사용되고, 백오프가 없으면 즉시 해제됩니다.
예외 시의 자동 해제와 releaseUsingBackoff()에 의한 수동 해제는 목적이 다릅니다.
  • 예외 시: 잡을 처리하지 못했으므로 Laravel이 백오프를 사용해 해제한다.
  • 수동 해제: 처리 자체는 정상이지만 외부 상태가 바뀔 때까지 나중에 다시 실행한다.
releaseUsingBackoff()의 대기 시간은 잡의 Backoff 또는 backoff()를 참조합니다. 수동 해제에서 다른 대기 시간을 명시하려면 release(초)를 사용합니다.

조합 예

다음 잡은 최대 1시간만 재시도하고, 처리되지 않은 예외는 3번까지 허용합니다. 예외 시나 결제 대기의 수동 해제에서는 10초·30초·60초 간격을 사용합니다.
RetryFor가 있으면 워커는 Tries(25)가 아니라 기한을 기준으로 통상의 시도 상한을 판단합니다. 둘 다 지정한다면 시간에 의한 기한을 주축으로 할지, 횟수에 의한 상한을 주축으로 할지를 정하고 그 의도를 테스트로 고정합니다. MaxExceptions는 그 어느 쪽과도 별개로 적용됩니다.

설정의 우선순위

잡과 워커의 설정을 섞어 쓸 때는 다음 우선순위로 생각하면 판단하기 쉽습니다. retryUntil 또는 RetryFor에 의한 기한이 있으면 워커는 tries 횟수보다 기한을 우선합니다. RetryFor와 retryUntil()을 동시에 사용하면 동적인 retryUntil()이 우선됩니다.

선택 방법

  • 외부 서비스의 복구를 기다리는 기한이 명확하면 RetryFor, 기한이 실행 시에 정해진다면 retryUntil().
  • API의 레이트 리밋이나 결제 상태 확인에는 Backoff와 releaseUsingBackoff().
  • 일시적인 락 대기는 많이 허용하고 실제 예외는 적게 하고 싶다면 Tries와 MaxExceptions를 조합한다.
  • 재시도가 부작용을 겹치는 처리에서는 시도 횟수뿐 아니라 멱등성과 외부 API 쪽의 중복 제어도 설계한다.
Tries와 RetryFor는 큐에 들어가는 이벤트 리스너나 알림에도 지정할 수 있습니다. 사용하는 대상의 페이로드가 같은 재시도 계약을 가지는지 확인하세요.

참고 링크

마지막 수정일 2026년 11월 16일