リトライとバックオフ

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 — 初期待機500〜1000 msを倍増させ、30〜60秒まで。リトライは3〜5回で打ち切ってください。
• 一時的なエラーによる500/5xx — 同じ形状で、初期値を少し短く（300 ms）。通常は素早く解消するためです。
• ストリーミングリクエスト — 再生を開始していない場合は、部分的なストリームのリトライは問題ありません。再生が始まった後は、新しい音声を継ぎ足すよりも失敗させる方が通常は良いでしょう。UXに基づいて判断してください。
• 長文の自動チャンク分割 — 両方のSDKは、内部の各セグメントに同じリトライポリシーを適用します。そのため、1回の長文呼び出しはセグメント単位でリトライ予算を持つことになります。

​

冪等性

​

避けるべきアンチパターン

• 4xx（429以外）のリトライ — 時間が経っても改善しません。リクエストを修正してください。
• 上限なし — 試行回数と合計経過時間には必ず上限を設けてください。
• ジッターなし — 固定遅延のリトライは、広範な障害発生時にサンダリングハード（thundering herd）パターンを引き起こします。
• バックオフなしのループ内リトライ — クレジットとレート制限の予算を数秒で使い切ります。

​

関連項目