ホーム/ガイド/べき等リクエスト

べき等リクエスト

POST リクエストの安全なリトライ方法。

概要

BlueAI API は Idempotency-Key ヘッダーによるべき等リクエストをサポートしています。ネットワークエラーなどで POST リクエストの結果が不明な場合、同じべき等キーで安全にリトライできます。

使い方

POST リクエストを送信する際に Idempotency-Key ヘッダーに一意の値を指定します。同じキーで再度リクエストした場合、API は最初のリクエストの結果をそのまま返します。

curl -X POST https://api.blueai.jp/api/v1/crm/deals \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -b cookies.txt \
  -d '{"name": "New Deal", "amount": 50000}'

キーの生成

UUID v4 の使用を推奨します。キーは十分にランダムで一意であることが求められます。

const idempotencyKey = crypto.randomUUID();

const res = await fetch("https://api.blueai.jp/api/v1/crm/deals", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  credentials: "include",
  body: JSON.stringify({ name: "New Deal" }),
});

有効期限

べき等キーは 24 時間保持されます。24 時間を過ぎると同じキーでも新しいリクエストとして処理されます。

適用範囲

GET、PUT、DELETE リクエストは本質的にべき等であるため、Idempotency-Key は POST リクエストにのみ適用されます。