Axios retry: 멱등성 키로 POST 안전하게 재시도하기

Axios 요청을 재시도하려면 axios-retry를 설치하고 axiosRetry(client, { retries, retryCondition, retryDelay })를 호출하세요. 실패한 요청이 retryCondition에 맞으면 retryDelay만큼 기다린 뒤 다시 전송됩니다. Axios 자체 문서는 같은 아이디어를 응답 인터셉터로 직접 구현해 보여 줍니다. 유료 API라면 네트워크 오류, 429, 5xx는 지수 백오프로 재시도하고, POST는 Idempotency-Key가 있을 때만 재시도하세요. 그래야 다시 보낸 요청이 두 번째 Job을 시작해 과금하는 대신 원래 Job을 돌려줍니다.

axios-retry 관련 내용은 README와 소스에서, Axios 관련 내용은 재시도와 오류 복구, 오류 처리, 요청 설정 페이지에서, Sume 관련 내용은 오류와 요청 한도 (영문), 오류와 비용 (영문), Format 호출하기 (영문)에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Axios는 HTTPS로 Sume를 직접 호출하며, Axios용 Sume 플러그인은 없습니다.

axios-retry는 기본적으로 무엇을 재시도하나요?

유료 생성 요청이라면 원하는 것보다 많이 재시도합니다. 기본 조건인 isNetworkOrIdempotentRequestError는 재시도하기에 안전하지 않다고 보는 코드를 제외하면 POST를 포함한 모든 메서드의 네트워크 오류를 받아들이고, GET, HEAD, OPTIONS, PUT, DELETE에서 받은 429나 5xx도 받아들입니다. 타임아웃된 요청(ECONNABORTED)은 절대 재시도하지 않으며, 취소된 POST는 건너뜁니다. 기본적으로 재전송은 지연 없이 나가지만, 내장 지연 함수는 모두 자체 값과 Retry-After 헤더 중 더 큰 값을 씁니다.

POST 재시도는 왜 위험하고, 무엇이 안전하게 만드나요?

네트워크 오류나 타임아웃만으로는 서버가 요청을 받았는지 알 수 없습니다. 서버가 받았다면 생성 요청을 무작정 다시 보낼 때 두 번째 유료 Job이 시작됩니다. 그래서 Sume 문서는 안전하지 않은 제출 요청을 Idempotency-Key 없이 재시도하지 말라고 안내합니다. 키가 있으면 재전송은 안전합니다.

• 같은 키, 같은 본문: 원래 영수증과 idempotency_hit: true가 담긴 200이 돌아옵니다. 두 번째 실행도, 두 번째 청구도 없습니다.
• 첫 요청이 아직 처리 중일 때 같은 키: 재시도할 수 있는 409 idempotency_key_in_use가 돌아옵니다. 약 일 초 기다린 뒤 다시 보내세요.
• 402, 503 등으로 실패한 생성 요청 뒤의 같은 키: 키가 해제되었으므로 원인을 고친 뒤 같은 키로 재시도하면 실행을 시작할 수 있습니다.
• 키는 요청한 시점이 아니라 주문 ID와 버전처럼 만들고 있는 대상에서 유도하세요. axios-retry는 같은 요청 설정을 다시 보내므로 모든 시도에 같은 키가 실립니다.

재시도 조건은 어떻게 작성하나요?

먼저 키 없는 POST를 거부하세요. 그다음 응답이 없는 요청을 재시도하되, 직접 취소한 요청은 제외하세요. 응답에 Sume의 오류 봉투가 있으면 그 retryable 플래그를 따르고, 없으면 Sume 자체 SDK가 재시도하는 것과 같은 집합인 408, 429, 5xx로 판단하세요. 지연은 500 ms 계수로 exponentialDelay를 재사용해 대략 1초, 2초, 4초에 최대 20%의 지터를 더하며, Retry-After나 봉투의 retry_after_seconds가 요구하면 더 오래 기다립니다. 키는 생성 요청마다 보내세요. 예를 들어 sume.post의 세 번째 인수로 { headers: { "Idempotency-Key": "order-1042-promo-v1" } }를 넘깁니다.

import axios from "axios";
import axiosRetry, { exponentialDelay } from "axios-retry";

const sume = axios.create({
  baseURL: "https://api.sume.com",
  timeout: 30_000,
  headers: { Authorization: `Bearer ${process.env.SUME_API_KEY}` },
});

axiosRetry(sume, {
  retries: 3,
  shouldResetTimeout: true, // every attempt gets the full 30 s
  retryDelay: (count, error) => {
    const hint = error.response?.data?.error?.retry_after_seconds ?? 0;
    return Math.max(exponentialDelay(count, error, 500), hint * 1000);
  },
  retryCondition: (error) => {
    const { config, response } = error;
    if (config?.method === "post" && !config.headers?.["Idempotency-Key"]) return false;
    if (!response) return error.code !== "ERR_CANCELED"; // network error or timeout
    const envelope = response.data?.error;
    if (typeof envelope?.retryable === "boolean") return envelope.retryable;
    return response.status === 408 || response.status === 429 || response.status >= 500;
  },
});

자동으로 재시도하면 안 되는 오류는 무엇인가요?

대부분의 4xx 응답입니다. 생성 단계의 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻이므로 호출을 고치세요. Sume 문서는 403 insufficient_scope를 루프에서 재시도하는 것을 가장 흔하고 가장 비용이 큰 실수로 꼽습니다.

• 402 insufficient_credits: 먼저 충전하세요. 재시도해도 같은 응답이 돌아옵니다.
• 409 idempotency_conflict: 키가 이미 다른 본문과 함께 쓰였습니다. 키를 유도하는 방식을 고치세요.
• 502 attachment_fetch_failed: 상태 코드는 5xx여도 원인은 여러분의 입력입니다. API 레퍼런스 예시에는 retryable: false와 next_action: fix_input이 나옵니다. 상태 코드만 보는 규칙은 이 요청을 다시 보내므로, 상태보다 봉투를 먼저 읽으세요.
• 취소된 요청: Axios는 이런 요청을 ERR_CANCELED로 표시하며, 응답을 기다리는 쪽도 없습니다.

브라우저의 Axios 네트워크 오류는 재시도로 해결되나요?

항상 그렇지는 않습니다. Axios 문서에 따르면 브라우저에서 ERR_NETWORK는 CORS나 혼합 콘텐츠(mixed content) 정책 위반일 수도 있으며, 같은 요청을 다시 보내도 정책은 바뀌지 않습니다. 유료 API라면 이 질문은 의미가 없습니다. Sume 문서는 API 키를 프론트엔드 JavaScript에 두지 않도록 하므로, 이 클라이언트는 서버에 있어야 합니다. 해결 방법은 브라우저에서 Sume API 호출 시 CORS 오류에서 설명합니다.

서버에서는 Sume의 TypeScript SDK를 쓰면 axios-retry가 필요 없습니다. createSumeClient는 기본적으로 이미 408, 429, 5xx와 전송 실패를 지수 백오프와 지터를 적용해 두 번 재시도하고, retry-after를 따르며, POST는 Idempotency-Key가 있을 때만 재시도합니다. Sume TypeScript SDK 빠른 시작을 참고하세요.