Home/Guides/Idempotent Requests

Idempotent Requests

How to safely retry POST requests.

Overview

The BlueAI API supports idempotent requests via the Idempotency-Key header. If a POST request result is uncertain due to network errors, you can safely retry with the same idempotency key.

How It Works

Include a unique value in the Idempotency-Key header when making a POST request. If you send another request with the same key, the API returns the result of the original request.

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}'

Generating Keys

We recommend using UUID v4. Keys should be sufficiently random and unique.

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" }),
});

Expiration

Idempotency keys are stored for 24 hours. After 24 hours, the same key will be treated as a new request.

Scope

GET, PUT, and DELETE requests are inherently idempotent, so the Idempotency-Key only applies to POST requests.