idempotency_conflict

HTTP status: 409

The Idempotency-Key on this request matched a key the server saw within the last 24 hours, but the request body differs from the original. The server refuses to execute, because honoring the key would return a cached response for a different operation.

Why this happens

• A key was reused across two semantically distinct requests.
• The key was derived from a hash of the body, and two different bodies collided. Keys must be UUID v4, never body-derived — see Idempotency.
• A retry mutated the request between attempts (e.g. a regenerated timestamp inside the body) while keeping the same key.

What to do

1. Mint a fresh UUID v4 for the new request. One key per logical operation; reuse it only for byte-identical retries of that same operation.
2. If you intended a retry, send the original body unchanged with the original key — the server returns the cached response without re-executing.
3. Confirm you are not deriving the key from the body; use crypto.randomUUID(), uuid.uuid4(), google/uuid, Guid.NewGuid(), or Str::uuid().

Example response

{
  "type": "https://zyins.isaapi.com/errors/idempotency-conflict",
  "title": "Idempotency key reused with different body",
  "status": 409,
  "detail": "Idempotency-Key '550e8400-e29b-41d4-a716-446655440000' was used at 2026-05-14T14:32:01Z with a different request body.",
  "code": "idempotency_conflict",
  "advice_code": "use_new_idempotency_key",
  "param": null,
  "request_id": "req_01HZK2N5GQR9T8X4B6FJW3Y1AS"
}

SDK exceptions

See also

• Error catalog
• Idempotency guide — the 24-hour replay window and the dedupe key
• conflict — the general resource-state conflict