재시도와 백오프

Documentation Index

Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​

재시도 대상

​

SDK 설정

from supertone import Supertone
from supertone.utils.retries import RetryConfig

client = Supertone(
    api_key=os.environ["SUPERTONE_API_KEY"],
    retry_config=RetryConfig(
        strategy="backoff",
        backoff={
            "initial_interval": 500,        # ms
            "max_interval": 60_000,         # ms
            "exponent": 1.5,
            "max_elapsed_time": 3_600_000,  # ms (1 hour cap)
        },
        retry_connection_errors=True,
    ),
)

import { Supertone } from "@supertone/supertone";

const client = new Supertone({
  apiKey: process.env.SUPERTONE_API_KEY,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 60_000,
      exponent: 1.5,
      maxElapsedTime: 3_600_000,
    },
    retryConnectionErrors: true,
  },
});

​

수동 재시도 패턴

import random
import time

def call_with_backoff(fn, *, max_attempts=5, base_ms=500, max_ms=60_000):
    for attempt in range(max_attempts):
        try:
            return fn()
        except (
            errors.TooManyRequestsErrorResponse,
            errors.InternalServerErrorResponse,
            errors.RequestTimeoutErrorResponse,
        ) as e:
            if attempt == max_attempts - 1:
                raise
            delay_ms = min(base_ms * (2 ** attempt), max_ms)
            # Jitter to avoid thundering herd
            delay_ms = delay_ms / 2 + random.uniform(0, delay_ms / 2)
            time.sleep(delay_ms / 1000)

​

적절한 백오프 선택

• 요청 수 제한으로 인한 429 — 초기 대기 5001,000 ms에서 시작해 3060초까지 두 배씩 증가시키고, 재시도 횟수는 3~5회로 제한합니다.
• 일시적 오류로 인한 500/5xx — 같은 형태이되, 보통 빠르게 해소되므로 조금 더 공격적으로 설정합니다(초기 300 ms).
• 스트리밍 요청 — 재생을 시작하기 전이라면 일부분 수신된 스트림을 재시도해도 무방하지만, 재생이 이미 시작된 후에는 새로운 오디오를 이어 붙이기보다 실패시키는 편이 보통 더 낫습니다. UX 기준으로 결정하세요.
• 장문 자동 청크 처리 — 두 SDK 모두 내부 분할된 각 세그먼트에 동일한 재시도 정책을 적용하므로, 단일 장문 호출은 세그먼트별로 재시도 예산을 갖습니다.

​

멱등성

​

피해야 할 안티 패턴

• 429 외의 4xx 재시도 — 시간이 지나도 해결되지 않습니다. 요청을 먼저 수정하세요.
• 상한 미설정 — 시도 횟수와 총 경과 시간에 반드시 상한을 두세요.
• 지터 미적용 — 고정 간격 재시도는 광범위한 장애 상황에서 thundering-herd 현상을 유발합니다.
• 루프 안에서 백오프 없이 재시도 — 크레딧과 요청 제한 예산을 수 초 만에 소진시킵니다.

​

관련 문서