エラー、冪等性、安全な再試行

一つの論理操作を変えない

有料の作成エンドポイントには8～200文字のIdempotency-Keyが必要です。一度作って正確なリクエストとともに保存し、タイムアウトや接続失敗時にも両方を再利用します。同じキーと正規化された本文は元の操作へ戻り、本文を変えると競合します。受理中のリクエストは再試行可能な進行中競合になる場合があります。

キーは最低24時間保持されますが、無期限の重複排除ではありません。範囲はアカウント、操作、APIキーの主体（MCPならOAuthクライアント）です。別キーに切り替えると同じ文字列でも新しいタスクになり得ます。不確実な作成中は認証情報を変える前に既存タスクを探します。新しい生成や変更したリクエストには再承認と新しい論理キーを使い、黙って新キーを作らないでください。

エラーの構造を読む

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}

説明用の例であり、メッセージ本文の一致を保証しません。HTTP状態とerror.codeで分岐し、retryableを見てrequest_idをサポート用に保持します。ヘッダー、画像、プロンプト、署名付きURLをログへ出さないでください。

対応を選ぶ

所有権エラーが意図的に404に見える場合があります。他人のIDを探らないでください。

再試行回数と時間を制限する

Retry-Afterは秒またはHTTP日付で扱い、なければジッター付き指数バックオフを使います。回数上限と全体の期限を設けます。ローカルの期限切れは受理済みリモートタスクの中止ではありません。読み取りは一時的な転送障害で再試行できます。不確実な有料作成は保存済みの冪等性キーと不変の本文でのみ再試行します。キーのないアップロードなど非冪等操作を無条件に再送しないでください。

期限に達したら既知のタスクIDを保存して後で再開します。終状態の失敗では新しい書き出し・生成の前に部分成果物を調べます。

アカウント上限と診断

PROVIDER_CONTENT_REJECTEDは現在、確認済みのSeedance審査拒否を表し、同じ内容で再試行する一時エラーではありません。タスクのcredits.status、credits.refunded、credits.releasedを読みます。credits.chargedは返還後の純額なので再度差し引かないでください。納品・書き出し前の確定拒否では元のワンクリック額が戻りますが、ローカルタイムアウトや書き出し失敗は同じ条件ではなく、返還は新たな有料生成の承認ではありません。

現在の上限はGET /accountで読み、応答のレート制限ヘッダーも参照します。キーを増やしてもアカウント容量は増えません。複数タスクのポーリングを同時刻に集中させないでください。サポートには公開リクエストID、分かるタスクID、時刻、コード、短い説明を送り、秘密と私的入力を伏せます。状態確認とダウンロードとPython例も参照してください。