API 문서 · 안정성

재시도 권장 사항

어떤 오류를 재시도할지, 어떻게 백오프할지.

상황	재시도 여부	방법
네트워크 타임아웃, 연결 끊김	예	같은 Idempotency-Key로 재시도
429 rate_limited	예	Retry-After만큼 기다린 뒤 재시도
500 internal_error	예	지수 백오프, 같은 멱등 키 사용
422 asset_not_ready	예	에셋이 available이 될 때까지 대기
400 / 401 / 403 / 404 / 409	아니요	요청을 수정한 뒤 다시 전송
402 한도 부족	아니요	한도를 충전하거나 Key 한도 또는 max_budget을 조정한 뒤 다시 전송
작업 failed	실패 코드에 따라 다름	작업 실패 코드의 권장 조치 참고. 다시 제출할 때는 새 멱등 키 사용

권장 백오프: 처음 1초, 이후 매번 2배씩 늘리고 0–500밀리초의 무작위 지터를 더하며 최대 5회까지 시도합니다. 플랫폼이 내부적으로 채널 단위 재시도와 전환을 이미 수행하므로 같은 작업을 중복 제출할 필요가 없습니다.

Node.js

// 서비스 측 고유 ID를 멱등 키로 사용: 타임아웃 후 재시도해도 작업이 중복 생성되지 않음
async function submit(order) {
  const key = `order-${order.id}-v${order.revision}`;
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch("https://cn-api.aitoken.tools/v1/videos/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AITOKEN_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(order.payload),
      });
      if (res.status < 500 && res.status !== 429) return res.json();
    } catch {
      // 네트워크 오류: 같은 key로 계속 재시도
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}