ネットワークは最悪のタイミングで切れます。サーバーは処理を終えたのに、応答が届かないときです。冪等キーは、そこでのリトライを安全にします。
仕組み
クライアントは、意図した 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 を悪化させる理由はレート制限を参照してください。