べき等性

一部のAPIは、同じ操作を誤って2回実行することなく、リクエストを安全に再試行するためのべき等性をサポートしています。
これは、API呼び出しが転送中に中断され、応答がない場合に役立ちます。たとえば、ネットワーク接続エラーが原因で保証契約を作成する要求が応答しない場合は、同じべき等キーを使用して要求を再試行し、作成される保証契約が1つだけであることを保証できます。

protegerのべき等性は、成功したか失敗したかに関係なく、任意のべき等キーに対して行われた最初の要求の結果のステータスコードと本文を保存することによって機能します。同じキーを使用した後続のリクエストは、500エラー（401エラーを除く）を含む同じ結果を返します。

べき等キーは、サーバーが同じ要求の後続の再試行を認識するために使用する、クライアントによって生成された一意の値です。一意のキーを作成する方法はクライアントサイド次第ですが、V4 UUID、または衝突を回避するのに十分なレンジを持つ別のランダムな文字列を使用することをお勧めします。

キーは、24時間以上経過するとシステムから自動的に削除されます。
元のキーが削除された後にキーが再利用されると、新しいリクエストが生成されます。
べき等層は、偶発的な誤用を防ぐために同じでない限り、パラメーターを元の要求およびエラーのパラメーターと比較します。

結果は、APIエンドポイントが実行を開始した場合にのみ保存されます。パラメーターが検証に失敗した場合、または要求が同時に実行されていた別のパラメーターと競合した場合、APIエンドポイントが実行を開始しなかったため、べき等の結果は保存されません。これらの要求を再試行しても安全です。

べき等キーを受け入れるPOSTリクエストには、APIドキュメントにオプションのヘッダーX-Idempotency-Keyが含まれます。