BroadRouter
始める

冪等キー(idempotency key)

更新日

冪等キーとは、決済や購入など状態を変えるリクエストにクライアントが付ける一意の値で、通常は UUID などのランダムな ID です。同じキーで同じリクエストが再送されると、サーバーは処理を 2 回実行せず、最初の結果を返します。

別名: 冪等キー、べき等キー、冪等性キー、冪等性、冪等なリクエスト、Idempotency-Key ヘッダー、idempotency key、Idempotency-Key header、idempotency token、idempotent request、idempotent retry

ネットワークは最悪のタイミングで切れます。サーバーは処理を終えたのに、応答が届かないときです。冪等キーは、そこでのリトライを安全にします。

仕組み

クライアントは、意図した 1 つの操作に対して一意のキーを作り、リクエストと一緒に送ります。サーバーはキーを結果とともに保存します。同じキーが再び届いたら、サーバーは処理をやり直さず、保存した結果を返します。

IETF の HTTPAPI ワーキンググループは、これを Idempotency-Key リクエストヘッダーとして標準化しています(ドラフト 08、2026 年 10 月、まだ RFC ではありません)。ドラフトはキーを “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request”(訳:クライアントが生成する一意の値で、リソースが同じリクエストの後続のリトライを識別するために使うもの)と説明し、UUID などのランダムな ID を推奨しています。ドラフトが定めるエラーは次のとおりです。

状況 ステータス
必須なのにキーがない 400 Bad Request
元のリクエストがまだ処理中 409 Conflict
同じキーを別のボディで再利用 422 Unprocessable Content

AWS の Builders’ Library も、クライアント側から同じことを指摘しています。“APIs with side effects aren’t safe to retry unless they provide idempotency.”(訳:副作用のある API は、冪等性を提供していない限り、安全にリトライできない)

なぜ重要か

指数バックオフによるリトライは標準的な手法で、多くの SDK は自動でリトライします。冪等性がなければ、タイムアウト後のリトライで注文や課金が 2 回発生することがあります。キーがあれば、最初の試行がどうなっていてもリトライは安全です。人が見ていないところで購入、予約、作成を行うエージェントやスクリプトにとって、中核となる仕組みです。

BroadNet Inference の場合

BroadNet は時間制キーの購入にこのパターンを使っています。POST /portal/keys/hourly は JSON ボディで request_id を受け取り、ドキュメントには “Idempotency is required for money safety”(訳:お金の安全のために冪等性が必須)と書かれています。

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

同じ request_id を再利用しても、別のキーが作られたり課金されたりはしません。タイムアウト、接続の切断、409 mint_in_progress、5xx の後は、同じ request_id でリトライしてください。再送には already_issued: true とキーのエイリアスが返ります。生のキーが含まれるのは、最初に成功した応答だけです。ドキュメントには “Never generate a replacement id until the original result is known.”(訳:元の結果がわかるまで、代わりの id を生成してはならない)とあります。

BroadNet は /v1/chat/completions や文字起こしについては冪等キーを記載していません。そちらで何をリトライすべきかはエラーコードとリトライを、やみくもなリトライが 429 を悪化させる理由はレート制限を参照してください。

よくある質問

新しい冪等キーはいつ生成すればよいですか?

新しい操作を意図したときだけです。1 つの操作のリトライには毎回同じキーを使い、最初の試行の結果がわかるまでは新しいキーを作らないでください。

LLM のチャット補完リクエストに冪等キーは必要ですか?

テキスト生成には永続的な副作用がないため、チャットリクエストが繰り返されても、通常はトークン代が再度かかるだけです。冪等キーが重要なのは、課金やリソース作成を伴う呼び出しです。BroadNet が冪等キーを記載しているのは時間制キーの購入だけで、チャット補完にはありません。

同じキーを別のリクエストボディで再利用するとどうなりますか?

IETF のドラフトでは、キーがすでに別のリクエストに結び付いているため、サーバーは 422 Unprocessable Content で拒否すべきとしています。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く