RetryOptions — @gj-kit/toss-payments

A public interface from @gj-kit/toss-payments/server. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

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

Signature, parameters, and return type

/**
 * 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;
}

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

Package: @gj-kit/toss-payments
Version: 0.6.1
Public entry: ./server
Source: GitHub