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

# 큐 잡의 재시도 정책

> Tries·RetryFor·MaxExceptions·Backoff를 조합해 Laravel 13의 큐 잡이 언제, 몇 번, 어떤 간격으로 재시도될지 설계합니다.

큐 잡의 재시도를 설계할 때는 "몇 번 시도할지", "언제까지 시도할지", "예외를 몇 번 허용할지", "다음 시도까지 몇 초 기다릴지"를 나누어 생각합니다. Laravel 13에서는 이를 잡의 Attribute와 메서드로 선언할 수 있습니다.

> [!NOTE]
>
> 이 페이지는 Laravel 13과 Framework `v13.42.0`을 대상으로 합니다. 기본적인 큐 사용법이 아니라 재시도 설정의 조합과 우선순위를 다룹니다.

| 결정할 것 | Attribute / 메서드 | 주요 용도 |
| - | - | - |
| 최대 시도 횟수 | `#[Tries]` / `tries()` | 시도 횟수에 상한을 둔다 |
| 재시도 기한 | `#[RetryFor]` / `retryUntil()` | 디스패치 후 정해진 시간 안에서만 시도한다 |
| 처리되지 않은 예외의 상한 | `#[MaxExceptions]` | 예외가 일정 횟수 발생하면 실패시킨다 |
| 재시도 간격 | `#[Backoff]` / `backoff()` | 예외 후나 수동 해제 후의 대기 시간을 정한다 |

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

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

### `Tries`: 횟수에 상한을 둔다

잡별 상한을 `Tries` Attribute로 선언할 수 있습니다. 워커의 `--tries`보다 잡 쪽의 지정이 우선됩니다.

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

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

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

실행 시의 조건으로 상한을 정하려면 `tries()` 메서드를 사용합니다. 이 메서드는 `Tries` Attribute보다 우선됩니다.

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

### `RetryFor`: 시간 범위를 지정한다

횟수가 아니라 큐에 투입된 뒤 재시도할 수 있는 시간을 지정하려면 `RetryFor`를 사용합니다. 이름 없는 위치 인수는 초 단위이며, `minutes`와 `hours`를 이름 있는 인수로 지정할 수도 있습니다.

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

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

다음 지정은 각각 초·분·시간을 나타냅니다.

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

`RetryFor`는 잡의 페이로드에 재시도 기한을 기록합니다. 워커는 그 기한이 지난 잡을 새로 실행하지 않습니다. `retryUntil()` 메서드나 `retryUntil` 프로퍼티가 있으면 그쪽이 `RetryFor`보다 우선됩니다. 또한 `retryUntil`이 유효한 잡에서는 `Tries`보다 시간에 의한 기한이 우선됩니다.

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

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

`retryUntil()`은 외부 서비스의 복구 시각이나 업무상의 마감처럼 잡의 내용에서 기한을 동적으로 정하는 경우에 적합합니다.

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

수동 `release()`나 락 획득 대기에 의한 해제는 계속 허용하면서, 처리되지 않은 예외가 계속되면 빨리 실패시키고 싶을 때가 있습니다. 이 경우 `Tries`와 `MaxExceptions`를 나누어 지정합니다.

```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
    {
        // release()에 의한 재시도는 허용하고,
        // 처리되지 않은 예외가 3번 발생하면 실패한다.
    }
}
```

이 예에서 잡은 최대 25번까지 시도할 수 있습니다. 다만 처리되지 않은 예외가 3번 발생하면 시도 횟수 상한에 도달하지 않았더라도 실패합니다. `MaxExceptions`는 `release()`에 의한 재시도 횟수를 세기 위한 설정이 아닙니다.

프로세스가 메모리 부족 등으로 크래시한 시도는 기본적으로 `MaxExceptions`의 예외 수에 포함되지 않습니다. 크래시도 예외로 세어야 한다면 `CountCrashesAsExceptions`를 추가합니다.

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

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

## 재시도 간격을 설정한다

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

### 고정 간격

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

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // 처리되지 않은 예외 후 10초 기다렸다가 재시도한다.
}
```

배열을 지정하면 시도마다 다른 간격을 설정할 수 있습니다. 배열 요소를 다 쓰면 마지막 값이 사용됩니다.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // 첫 번째 재시도까지 10초, 두 번째까지 30초,
    // 세 번째 이후는 60초 기다린다.
}
```

조건에 따라 간격을 바꾸려면 `backoff()`를 사용합니다. `backoff()`는 `Backoff` Attribute보다 우선됩니다.

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

잡별 지정이 없으면 워커의 `--backoff`가 사용됩니다.

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

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

외부 API가 "처리 중"을 반환했을 때처럼 예외를 던지지 않고 잡을 나중에 다시 실행하고 싶다면 `releaseUsingBackoff()`를 사용합니다. 잡에 설정한 백오프 배열 중 현재 시도에 해당하는 값으로 해제합니다. 값을 다 쓰면 마지막 값이 사용되고, 백오프가 없으면 즉시 해제됩니다.

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

        // 결제 완료 후의 처리
    }

    private function paymentIsPending(): bool
    {
        // 결제 서비스의 상태를 확인한다.
        return true;
    }
}
```

예외 시의 자동 해제와 `releaseUsingBackoff()`에 의한 수동 해제는 목적이 다릅니다.

* **예외 시**: 잡을 처리하지 못했으므로 Laravel이 백오프를 사용해 해제한다.
* **수동 해제**: 처리 자체는 정상이지만 외부 상태가 바뀔 때까지 나중에 다시 실행한다.

`releaseUsingBackoff()`의 대기 시간은 잡의 `Backoff` 또는 `backoff()`를 참조합니다. 수동 해제에서 다른 대기 시간을 명시하려면 `release(초)`를 사용합니다.

## 조합 예

다음 잡은 최대 1시간만 재시도하고, 처리되지 않은 예외는 3번까지 허용합니다. 예외 시나 결제 대기의 수동 해제에서는 10초·30초·60초 간격을 사용합니다.

```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
    {
        // 외부 서비스를 호출해 청구서를 처리한다.
    }
}
```

`RetryFor`가 있으면 워커는 `Tries(25)`가 아니라 기한을 기준으로 통상의 시도 상한을 판단합니다. 둘 다 지정한다면 **시간에 의한 기한을 주축으로 할지, 횟수에 의한 상한을 주축으로 할지**를 정하고 그 의도를 테스트로 고정합니다. `MaxExceptions`는 그 어느 쪽과도 별개로 적용됩니다.

## 설정의 우선순위

잡과 워커의 설정을 섞어 쓸 때는 다음 우선순위로 생각하면 판단하기 쉽습니다.

| 대상 | 우선되는 설정 | 폴백 |
| - | - | - |
| 최대 시도 횟수 | `tries()` | `#[Tries]`, `queue:work --tries` |
| 재시도 기한 | `retryUntil` 메서드 / 프로퍼티 | `#[RetryFor]` |
| 처리되지 않은 예외의 상한 | `#[MaxExceptions]` | 지정하지 않으면 상한 없음 |
| 예외 후의 백오프 | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| 수동 해제의 대기 시간 | `releaseUsingBackoff()`의 잡 설정 | `release(초)` |

`retryUntil` 또는 `RetryFor`에 의한 기한이 있으면 워커는 `tries` 횟수보다 기한을 우선합니다. `RetryFor`와 `retryUntil()`을 동시에 사용하면 동적인 `retryUntil()`이 우선됩니다.

## 선택 방법

```mermaid theme={null}
flowchart TD
    A["재시도 조건을 정한다"] --> B{"횟수로 멈출까?"}
    B -->|예| C["#[Tries]"]
    B -->|아니오| D["#[RetryFor] 또는 retryUntil()"]
    C --> E{"처리되지 않은 예외만 빨리 실패?"}
    D --> E
    E -->|예| F["#[MaxExceptions]"]
    E -->|아니오| G["불필요"]
    F --> H{"대기 시간을 바꿀까?"}
    G --> H
    H -->|예| I["#[Backoff] / backoff()"]
    H -->|상태 대기| J["releaseUsingBackoff()"]
    H -->|아니오| K["워커의 기본값"]
```

* 외부 서비스의 복구를 기다리는 기한이 명확하면 `RetryFor`, 기한이 실행 시에 정해진다면 `retryUntil()`.
* API의 레이트 리밋이나 결제 상태 확인에는 `Backoff`와 `releaseUsingBackoff()`.
* 일시적인 락 대기는 많이 허용하고 실제 예외는 적게 하고 싶다면 `Tries`와 `MaxExceptions`를 조합한다.
* 재시도가 부작용을 겹치는 처리에서는 시도 횟수뿐 아니라 멱등성과 외부 API 쪽의 중복 제어도 설계한다.

> [!NOTE]
>
> `Tries`와 `RetryFor`는 큐에 들어가는 이벤트 리스너나 알림에도 지정할 수 있습니다. 사용하는 대상의 페이로드가 같은 재시도 계약을 가지는지 확인하세요.

## 참고 링크

* [Laravel 공식 문서: Max job attempts and timeout](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Laravel 공식 문서: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Laravel 공식 문서: 수동 해제와 `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Laravel 공식 문서: 실패한 잡의 백오프](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [`RetryFor` Attribute](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [`Backoff`·`Tries`·`MaxExceptions` Attribute](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

- [2026년 9월 Laravel 업데이트](https://kawax.biz/ko/blog/changelog/202609.md)
- [Laravel 13 신기능 정리](https://kawax.biz/ko/blog/laravel-13-new-features.md)
- [패키지의 큐 잡과 업데이트 시 호환성](https://kawax.biz/ko/advanced/package-queue-jobs.md)
- [Laravel Horizon](https://kawax.biz/ko/horizon.md)
- [큐 잡 실행 제어](https://kawax.biz/ko/advanced/queue-job-control.md)


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