べき等性

AstroWay APIのすべてのエンドポイントは自然にべき等性を持っています：同じ入力は常に同じ出力を生成し、副作用はありません（クレジットの消費と使用状況のロギングを除く）。

これは、ネットワークエラー時のリトライが安全であることを意味します。しかし、重複したリクエストがクレジットを二重に消費しないようにするには、Idempotency-Keyヘッダーを渡す必要があります。

使用方法

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - 64文字までの任意の文字列で、各論理操作に対して一意である必要があります。推奨されるのはULIDまたはUUID v4です。

保証

最初のリクエストから24時間以内に、同じキーを使用した重複リクエストは、再計算せずに同じレスポンスを返し、クレジットを消費しません。
リクエストのbodyが元と異なる場合：idempotency_key_reuseコードで409 Conflictが返されます。
24時間後、キーは破棄され、同じキーでの新しいリクエストは通常のリクエストとして扱われます。

必要な場合

外部システム（例えば、決済プロバイダーまたはCRM）からリトライが送信されるwebhookハンドラ（イベントを解析して計算を行う）
リトライが標準的な障害時の動作であるバックグラウンドジョブ
テストが再実行される可能性のあるCI/CDパイプライン

「ユーザーがボタンをクリック→カードを表示」といった通常のインタラクションでは、べき等性は不要です - ユーザーは結果を見ることができ、通常は重複したクリックはありません。

使用しない場合

同じリクエストでクレジットを節約するためにキーを設定しない：これにはX-Cache（無料、5分）があります
hash(body)からキーを生成しない：そうすると、Idempotency-Keyのデフォルトの動作（bodyの不一致時の重複409）を失います

参考になりましたか？

編集を提案

最終更新日: 2026/09/25