---
title: "冪等リクエスト"
description: "KOMOJU APIの冪等リクエストのサポートについて — X-KOMOJU-IDEMPOTENCYヘッダーを使用して、重複したキャプチャや返金を発生させることなく操作を安全にリトライする方法を説明します。"
url: "https://docs.komoju.com/ja/docs/introduction/idempotent-requests"
source_url: "https://docs.komoju.com/ja/docs/introduction/idempotent-requests.md"
language: ja
last_modified: "2026-03-31"
---

KOMOJU APIは冪等リクエストをサポートしており、各操作が最大1回だけ実行されることを保証します。これは、リクエストが失敗した際に自動再試行を利用する顧客にとって、たとえば重複したキャプチャや返金を回避するために重要です。

冪等リクエストは`POST` APIリクエストでサポートされています。冪等リクエストを利用するには、クライアントは各リクエストごとに一意で空でない冪等性キーを生成し、それを`X-KOMOJU-IDEMPOTENCY`ヘッダーに含めて送信する必要があります。ランダムなUUIDの使用が推奨されますが、便宜上、ユーザー自身のフォーマットを選択することも可能です。冪等性キーは、各リクエストに対してグローバルに一意でなければなりません。また、冪等性キーの長さは最大100 ASCII文字に制限されています。

クライアントが何らかの理由でリクエストを再試行する場合、そのリクエストのすべての再試行には、同じ冪等性キーとリクエストボディを使用する必要があります。KOMOJUが指定された冪等性キーを持つリクエストをすでに処理している場合、要求された操作を再実行することなく、最初のリクエストと同じ応答が返されます。

最初のリクエストが応答を生成する前にリクエストが再試行された場合、HTTP 409が代わりに返されます。

> ⚠️ **Warning:** 冪等性キーは、初回使用から最大24時間有効で、その後は再利用可能になります。そのため、最初のリクエストから24時間以上経過した再試行は、冪等性が保証されない可能性があります。