レート制限とバージョン管理
/v1 を現在のパス契約として扱い、固定したリクエスト上限ではなく応答ヘッダーを使います。
認証済み応答は x-ratelimit-limit、x-ratelimit-remaining、x-ratelimit-reset を公開し、保護された一部のルートは Retry-After も返します。上限値は動的な場合や unlimited と報告される場合があります。
- ステータス、エラーコード、
x-request-idを記録します。 429では、存在する場合Retry-Afterまたはx-ratelimit-resetまで待ちます。- 指数バックオフ、ジッター、最大遅延、最大試行回数を設定して再試行します。
- 再試行の集中を起こさず、クライアントの同時実行数を制限します。
- ルートが安全な再実行を明記しない限り、非冪等な作業を再試行しません。
ベースパスに /v1 を保持し、変更前にドキュメントに対して移行をテストします。現在のルートに別の公開バージョンヘッダーは不要です。
期待される結果: クライアントが重複作業なしで一時的制限から復旧し、互換性のないパスでは明確に失敗します。