冪等キー（Idempotency key）

タイムアウトや 5xx のあと同じ論理リクエストを安全にリトライし、二重課金を避けるには、操作ごとに 1 つの冪等キーを保存します。新しい論理操作には新しい UUID、同一操作のリトライや復旧には保存済みの同じキーと完全なリクエストを使います。 同じ内容を意図的に再評価するのは新しい操作であり、リトライではありません。操作キーを使うと、応答が失われても評価や課金を重ねずに成功した結果を復元できます。適用範囲はホスト型 API とセッションの Playground までであり、単体で動く SDK adapter や直接のプロバイダに一般に適用されるものではありません。

よくある質問

Q: System One API の冪等キーとは？ A: クライアントが生成するトークンです。リトライ時に同じ意思決定結果を返し、クレジットの二重消費を防ぎます。

Q: いつ送りますか？ A: タイムアウト、ネットワークエラー、5xx のあとに、同じ論理上の意思決定をリトライするときです。

なぜ冪等キーが必要か

同じリクエストを再送すると、サービス側は新しい評価として扱い、クレジットをもう一度消費します。冪等キーを使うと、同じキーで再送された要求は保存済みの結果を返し、新しい評価も新しい課金も行いません。したがって、二重課金を避けたい処理では「失敗したら同じキーでもう一度送る」ことが基本になります。

逆に、リトライのたびに新しいキーを生成すると二重課金の防げません。 キーが違えば別の操作として扱われるためです。復旧のためのキーは、最初の送信の前にリクエストと一緒に保存しておく必要があります。

操作ごとに 1 つのキーを保存する

操作ごとに Idempotency-Key ヘッダーを送ります。最初の送信の前に UUID を一度だけ生成し、完全なリクエストと一緒に保持します。グローバルな環境変数キー、ジョブ間で共有する固定値、内容のハッシュは使わないでください。同じ内容でも別々の課金対象の評価になりうります。キーは 1〜128 文字で、英字か数字で始め、その後に英字、数字、ドット、アンダースコア、コロン、ハイフンを続けられます。

リトライでは、ホスト型クイックスタートで作成した同じ operation オブジェクトを使います。次の例は evaluate() の呼び出しを置き換え、client を再利用します。操作の作成や UUID の生成は行いません。

const result = await client.evaluate(operation.request, {
  maxRetries: 0,
  timeoutMs: 30_000,
  headers: { 'Idempotency-Key': operation.idempotencyKey },
});

クイックスタートは操作をメモリ上にしか保持しません。スクリプトを実行するたびに新しい課金対象の操作が始まります。 実際のアプリケーションでは、操作全体をキーと完全なリクエスト（選択したモデルを含む）とともに、アプリケーションのジョブ記録へ最初の送信の前に永続保存してください。クラッシュ後は新しい UUID を生成したりリクエストを組み立て直したりせず、その記録を読み込みます。リトライコードの中で新しいキーを生成すると、もう一度課金される可能性があります。

HTTP リファレンスには、curl での同等のヘッダーが載っています。SDK も Fetch transport も、冪等キーを自動的に生成しません。

リクエストを変更しない

キーはアカウント単位で、そのアカウントのすべての API キーとセッションの Playground に及びます。他のアカウントは別の名前空間です。同じアカウントの別の有効な API キーでも操作を復旧できますが、失効したキーは認証できません。API キーがセッション専用エンドポイントへ呼べるようになることもありません。

サービスは、検証済みの正規化リクエスト（実効モデル、コンテキスト、質問、criteria、受け入れられた拡張フィールドを含む）を比較します。整形の空白やオブジェクトのキー順は影響しません。配列の順序、Score ルーブリックの順序、フィールドの値、null と省略の違いは影響します。同じキーで別のリクエストを送ると 409 idempotency_conflict が返ります。

model は現在のモデル一覧から明示的な ID を送って保存してください。モデルを省略すると比較の前にサービスの既定へ解決されます。明示的なエイリアスやバージョン名もリクエストの同一性の一部です。復旧時に、要求した ID をレスポンスの解決済みモデルに置き換えないでください。

小数の同一性は厳密に保たれます。9007199254740993 と 9007199254740992 は異なり、1e-400 と 0 も異なります。同じ小数の表記は等しく扱われます。ヘッダーやキー名に秘密情報を入れないでください。

記録された結果に従う

成功したリプレイには X-Idempotency-Replayed: true、X-System-One-Credits: 0、元の X-Request-Id が含まれ、可能な場合は元のモデルサービスの追跡ヘッダーも保持されます。保存済みの応答を再利用し、モデルを再評価したり、値を再丸めしたり、本文に System One の replayed、billing、request_id フィールドを追加したりはしません。

リプレイの試行もアカウントの意思決定レート制限に算入されます。リプレイはプラットフォームのクォータを消費しますが、新しい課金は発生しません。応答は Cache-Control: no-store を使い、ブラウザやプロキシの通常のキャッシュは冪等性の仕組みではありません。

24 時間のウィンドウ

完了した操作は、リクエスト作成から 24 時間、そのキーで復旧できます。その時間を超えると、同じキーで新しい課金対象の操作を開始できます。期限切れのキーエラーが返るとは限りません。これは恒久的な重複防止ではありません。

操作キーがない場合、同じリクエストの繰り返しは別の評価です。重要な回答はリプレイの長期保存に依存せず、アプリケーション側で保存してください。

通常の失敗した評価は、エラーレスポンスの前に予約していたクレジットを返します。中断によって操作が保留のままになることがあります。15 分を超えて保留されたリクエストは照合の対象になりますが、これは即時の完了や返金の期限ではありません。結果が分かるまで元のキーとリクエスト ID を保持してください。保留中の操作が未解決のまま 24 時間経過したことは、24 時間後に代行操作を作る許可ではありません。

リクエストが 503 request_reconciliation_pending を返した場合、課金はまだ確定していません。X-System-One-Credits は省略されます。無いことは 0 を意味しません。復旧が即座に得られるとは限りません。元のキーと X-Request-Id を保持し、コンソールの利用状況を確認し、結果が不明なままなら support@system-one.devへ連絡してください。エラーを回避するためだけに新しいキーへ切り替えないでください。

SDK のリトライ設定

SDK の例は maxRetries: 0 で自動リトライを無効にし、アプリケーションが上の表に従って結果を確認できるようにしています。SDK のリトライポリシーはネットワークエラーと一部の HTTP 失敗をリトライしますが、異なる 409 の状態を自動的に解決することはありません。リトライを有効にする場合でも、保存済みの同じキーと本文が必要です。リトライを無効にしても、応答が失われたサーバー側の操作は取り消されません。サービスはモデルの推論を自動的にリトライしません。

core の APIError は statusCode、requestId、retryAfterMs を公開しますが、本文全体や分類ヘッダーは含みません。競合・保留・失敗を区別するには Fetch を使って X-System-One-Error-Code を読みます。Retry-After は秒数または HTTP 日付です。X-System-One-Error-Source も確認してください。モデルサービスの 401 は、System One のログインが期限切れという意味ではありません。エラーリファレンスを参照してください。

よくある間違い

• リトライのたびに新しいキーを生成する。 二重課金を防げません。既存操作のキーを使ってください。
• 同じキーで別の本文を送る。 409 idempotency_conflict になります。元の本文を復元するか、新しいキーを使ってください。
• キーを生成してから初めて送信する。 応答が失われると、そのキーを復元できません。最初の送信の前に保存します。
• 操作の保存をスクリプトの実行のたびに作り直す。 再実行は復旧ではなく、新しい課金対象の操作です。

内部リンク

API リファレンス、API エラーコード、API バージョニング、クレジットと課金、TypeScript SDKを参照してください。