dosya APIのリクエスト制限に対処する

dosyaのリクエスト制限ヘッダーを読み、Retry-Afterに従い、上限付きのランダムな待機を加えて安全に再試行します。一時的な429でリクエストを繰り返し続けないようにします。

dosyaには複数の制限があります。一般の認証済み通信とアップロード通信はユーザーあたり毎分300リクエスト、一覧取得は毎分600リクエスト、認証済みIP通信はデスクトップ同期の例外を除き毎分600リクエストに制限されます。APIキーにも独自の毎分リクエスト数の上限を設定できます。

始める前に

すべてのレスポンスでX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetを確認してください。一般の制限では成功したリクエストにもこれらのヘッダーが含まれます。
ステータスが429の場合、本文を解析する前にRetry-Afterを読んでください。キーごとの拒否ではThis API key has exceeded its requests-per-minute limitと表示される場合があり、必ず含まれるのはRetry-Afterのみです。
サーバーが指定した時間待機し、並列ワーカーが同時に再開しないよう短いランダムな待機時間を加えてください。不正な値や過大な待機時間にはジョブの期限に応じた上限を設けます。
待機後に読み取りまたは冪等なアップロードを再試行してください。移動、名前の変更、ゴミ箱への移動などの結果が不明な変更操作は自動で再送せず、リモートの状態を確認します。
再試行回数を制限してください。dosya CLIでは最大3回再試行し、代替の待機時間は1秒、3秒、8秒で、有効なRetry-Afterの値は最大60秒です。
認証情報をログに記録せず、ルート、ステータス、試行回数、待機時間を記録してください。リセットの時間枠をすべて経過しても429が繰り返される場合は同時実行数を減らします。

クライアントは連続してリクエストを送らずに待機し、制限に余裕ができると再試行に成功し、定めた再試行回数を使い切ると停止します。自動処理はヘッダーが同一だと仮定せず、キー単位の上限とユーザーまたはIP単位の広い制限を区別します。

Retry-Afterがない場合 ランダムな待機を加えた控えめな指数バックオフを使用してください。CLIの代替値は1秒、3秒、8秒です。

変更操作のステータスが届く前にタイムアウトした場合 対象または受領情報のエンドポイントを読み取ってください。その操作で冪等性が明記されている場合にのみ再送します。

リセット後も429が続く場合 同時実行数を減らし、APIキーに設定された毎分リクエスト数の上限を確認してください。新しいキーを作成してもユーザーまたはIP単位の保護は解除されません。