冪等なリクエスト

UnivaPay APIでは冪等なリクエストを行うことができます。冪等性は強力な安全性を提供し、予期しない理由などで、1つのリクエストが複数回実行されないようにします。

冪等性リクエストは POST と PATCH メソッドでのみ利用でき、有効な認証クレデンシャルを指定し、リクエストヘッダに Idempotency-Key キーで冪等性キーを指定する必要があります。この冪等性キーは任意の文字列を指定できますが、UUIDのように十分にランダムに生成された文字列を使用することを推奨します。

利用可能な場面では（特にトランザクショントークン、課金、定期課金、返金などの作成や更新時）常に冪等性リクエストを使用することをお薦めします。

ただし、冪等性の保証は現在ベストエフォートで提供されており、冪等性のチェックができない状態が発生する可能性があります。この場合、Idempotency-Status ヘッダに error が設定され、リクエストされた内容は 処理されます。

冪等性リクエストの仕組み

リクエストに冪等性キーが指定された場合、UnivaPay APIはまず、以前に同じキーのリクエストが処理されたかを確認します。

既に処理されていた場合、APIはそのリクエストを再度処理せずに、API内部のキャッシュに保存されている過去のレスポンスを返却します。

まだ処理されていなかった場合、APIは通常どおりリクエストを処理し、将来冪等性リクエストが来る時に備え、レスポンスの内容を冪等性キーをキーとしてAPI内部のキャッシュに保存します。

冪等性キーの有効期間は24時間です。同じ冪等性キーの2回目リクエストがこの期限を過ぎてしまった場合、APIはこれを1回目のリクエストとみなして実行してしまいます。

冪等性リクエストのレスポンスには、Idempotency-Status ヘッダが含まれます。これは下記のいずれかの値をとります:

• disabled: 冪等性リクエストをサポートしていません。
• successfully_stored: このレスポンスは指定された冪等性キーとして保存されました。これはキーが使用された初回に発生します。同じキーを使用した次回のリクエストはこの保存されたレスポンスが返されます。
• retrieved_idempotent_response: リクエストは実際には処理されず、指定した冪等性キーとして保存されているレスポンスが返されました。
• error: API内部のキャッシュからレスポンスの取得する時、もしくはキャッシュに処理結果を保存時に何らかのエラーが発生した為、冪等性のチェックができませんでした。リクエストされた処理は実行されています。
• conflicting_key: 指定された冪等性キーが以前に異なるAPIやメソッドで使用されています。