> ## 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の設定方法。
このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/docs/production/retries-and-backoff)もあわせてご確認ください。
一時的な失敗（`429`、`408`、`500`、ネットワーク切断）は、あらゆるネットワークサービスで通常発生します。適切な対応は、**ジッター付きの指数バックオフ**をリトライ可能なエラーに対してのみ適用することです。両方のSDKは、すぐに使える設定可能なリトライポリシーを標準で備えています。
## リトライ対象
| Status / failure | Retryable? | Notes |
| ----------------------------------------------- | :--------: | ---------------------------- |
| `408 Request Timeout` | ✅ | サーバー側 — 短時間待機してリトライ。 |
| `429 Too Many Requests` | ✅ | レート制限。バックオフ。 |
| `500 Internal Server Error` | ✅ | 一時的なものとして扱う。 |
| `502`, `503`, `504` | ✅ | ネットワーク/上流 — バックオフを伴うリトライ。 |
| ネットワークエラー（DNS、broken pipe、connect timeout） | ✅ | リトライ — 純粋なトランスポート障害です。 |
| `400`, `401`, `402`, `403`, `404`, `413`, `415` | ❌ | 呼び出し側の問題 — まずリクエストを修正してください。 |
## SDKの設定
両方のSDKは、クライアントレベルおよび呼び出し単位でリトライ設定を受け付けます。
```python theme={"dark"}
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,
),
)
```
```typescript theme={"dark"}
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,
},
});
```
この設定では、SDKがデフォルトでリトライ可能とするステータスコード（`429`、`5xx`）に対して指数バックオフでリトライを行い、リトライ間隔は最大1分、合計時間は最大1時間に制限されます。レイテンシSLOに合わせて数値を調整してください。
## 手動リトライパターン
REST APIを直接呼び出す場合や、SDKを独自のロジックでラップしたい場合：
```python theme={"dark"}
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回の長文呼び出しはセグメント単位でリトライ予算を持つことになります。
## 冪等性
Supertone API呼び出しは**結果として冪等**です — 同じリクエストは同じ音声出力（合成のわずかなばらつきを除く）を生成します。成功したものの中断されたリクエストをリトライしても、元のリクエストが課金対象の音声を生成していない限り、クレジットが二重に請求されることはありません。
ボイスクローンのアップロードについては、アップロードが完了した場合はリトライのたびに別々のボイスが作成されます。ネットワークの瞬断後に再アップロードする場合は、再投稿する前に前回の試行が実際に完了しているかを確認してください。そうでないと、`list_custom_voices`に重複したボイスが残ってしまいます。
## 避けるべきアンチパターン
* **`4xx`（`429`以外）のリトライ** — 時間が経っても改善しません。リクエストを修正してください。
* **上限なし** — 試行回数と合計経過時間には必ず上限を設けてください。
* **ジッターなし** — 固定遅延のリトライは、広範な障害発生時にサンダリングハード（thundering herd）パターンを引き起こします。
* **バックオフなしのループ内リトライ** — クレジットとレート制限の予算を数秒で使い切ります。
## 関連項目
そもそも何が`429`を引き起こすのか。
エラーコードとSDKエラークラスの完全リファレンス。