RetryOptions — @gj-kit/toss-payments

@gj-kit/toss-payments/server에서 공개하는 interface입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { RetryOptions } from '@gj-kit/toss-payments/server';

시그니처, 매개변수, 반환 타입

/**
 * retry — 실측 근거 하드 가드 자동 재시도 (설계 §3.4, 기본 꺼짐).
 *
 * 재시도 허용 조건은 **설정으로 확장 불가, 코드에 고정**이다(Phase 5 실측이 근거인 하드 불변식):
 * 1. GET: TransportFailure만 재시도 (자체 멱등 — 문서).
 * 2. Idempotency-Key가 실제 부착된 POST/DELETE:
 *    (a) TransportFailure — 동일 키+동일 body 재전송은 서버 도달 시 바이트 동일 재생,
 *        미도달 시 재실행(Phase 0 실측 — 이중 실행 없음).
 *    (b) 409 IDEMPOTENT_REQUEST_PROCESSING — 문서 지시("다시 요청해서 응답을 확인하세요") 준수.
 * 3. 키 없는 POST/DELETE(confirm 기본 정책): 어떤 실패든 자동 재시도 절대 없음 — 이중 승인
 *    방지. `retryable: true`여도 무시. confirm에 retry 효과를 받으려면
 *    `options.idempotencyKey` 명시가 전제다.
 * 4. 토스 4xx/5xx 에러 응답: 재시도 안 함 — 4xx는 멱등 재생 실측 확정(같은 키 재시도 =
 *    15일간 같은 에러 재생), 5xx는 재생 여부 미실측이라 보수 배제. PROVIDER_ERROR 등
 *    `retryable: true`도 포함해 배제 — 그 재시도는 "새 멱등키 + 상황 판단"이 필요한
 *    호출자 의사결정이다(§7-3).
 *
 * 역할 구분: 이 옵션은 "요청 내" 자동화다 — cancel의 CancelRetryTicket은 "요청 간(큐 저장
 * 후)" 수동 재실행용으로 그대로 유지·동봉된다. 409 재시도 후 원 요청이 4xx로 끝났으면 그
 * 에러를 재생받고 종료한다 — 처리 결과 확인이라는 올바른 동작이다.
 *
 * ⚠ 기본값 최악 지연 +10.5s(+ 시도별 timeout) — 요청 경로가 아닌 배치/큐 소비자에서 켜라.
 * confirm 경로 권장값은 maxAttempts 2. 409 폴링은 테스트 환경 분당 100건 쿼터를 소모한다.
 */
interface RetryOptions {
    /** 총 시도 횟수(최초 포함). 기본 3. 리터럴 유니언 — 폭주 설정 원천 차단. */
    readonly maxAttempts?: 2 | 3 | 4 | 5;
    /**
     * 시도 간 지연(ms). 기본 [500, 2_000, 8_000], full jitter ±25% 자동. 부족하면 마지막 값 재사용.
     * 각 값은 0~60_000의 안전한 정수여야 하며 빈 배열은 허용하지 않는다.
     */
    readonly delaysMs?: readonly number[];
    /**
     * reason이 2종 리터럴로 고정 — toss retryable류로 확장하려면 공개 타입 변경이 필요하도록
     * 봉인(§7-3). nextDelayMs는 jitter 적용 후 값. 이 콜백의 throw는 삼켜진다(요청 무간섭).
     */
    readonly onRetry?: (info: {
        readonly attempt: number;
        readonly reason: 'transport' | 'idempotent-processing';
        readonly nextDelayMs: number;
        readonly path: string;
    }) => void;
}

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

패키지: @gj-kit/toss-payments
버전: 0.6.1
공개 entry: ./server
소스: GitHub

구현 주석

retry — 실측 근거 하드 가드 자동 재시도 (설계 §3.4, 기본 꺼짐).

재시도 허용 조건은 설정으로 확장 불가, 코드에 고정이다(Phase 5 실측이 근거인 하드 불변식):

GET: TransportFailure만 재시도 (자체 멱등 — 문서).
Idempotency-Key가 실제 부착된 POST/DELETE: (a) TransportFailure — 동일 키+동일 body 재전송은 서버 도달 시 바이트 동일 재생, 미도달 시 재실행(Phase 0 실측 — 이중 실행 없음). (b) 409 IDEMPOTENT_REQUEST_PROCESSING — 문서 지시(“다시 요청해서 응답을 확인하세요”) 준수.
키 없는 POST/DELETE(confirm 기본 정책): 어떤 실패든 자동 재시도 절대 없음 — 이중 승인 방지. retryable: true여도 무시. confirm에 retry 효과를 받으려면 options.idempotencyKey 명시가 전제다.
토스 4xx/5xx 에러 응답: 재시도 안 함 — 4xx는 멱등 재생 실측 확정(같은 키 재시도 = 15일간 같은 에러 재생), 5xx는 재생 여부 미실측이라 보수 배제. PROVIDER_ERROR 등 retryable: true도 포함해 배제 — 그 재시도는 “새 멱등키 + 상황 판단”이 필요한 호출자 의사결정이다(§7-3).

역할 구분: 이 옵션은 “요청 내” 자동화다 — cancel의 CancelRetryTicket은 “요청 간(큐 저장 후)” 수동 재실행용으로 그대로 유지·동봉된다. 409 재시도 후 원 요청이 4xx로 끝났으면 그 에러를 재생받고 종료한다 — 처리 결과 확인이라는 올바른 동작이다.

⚠ 기본값 최악 지연 +10.5s(+ 시도별 timeout) — 요청 경로가 아닌 배치/큐 소비자에서 켜라. confirm 경로 권장값은 maxAttempts 2. 409 폴링은 테스트 환경 분당 100건 쿼터를 소모한다.