Skip to content

Idempotency Key Reused

URI: https://docs.ankatech.co/errors/idempotency-key-reused
HTTP Status: 422 Unprocessable Entity

When you see this

A request carried an Idempotency-Key the tenant has already used with a different request. The Admin API remembers each key with the SHA-256 of the request it was first used with (the path and the canonical body); a later request with the same key must be identical, because it is treated as a retry of the first one. Nothing was executed and no audit row was written.

Two operations reserve an Idempotency-Key:

Operation Header Same key, other request
POST /api/v3/admin/tenants/{tenantId}/compliance-remediation/{packId}/actions/{actionKey}/executions Required, a UUID Another key list, target or basis
POST /api/v3/admin/tenants/{tenantId}/keys/{kid}/rotations (rotateKey) Optional, 1 to 255 visible ASCII characters Another kid or another newMaterial; the key service is not called

A key belongs to the tenant that used it: another tenant's use of the same string is a different key. For rotateKey a key also belongs to the user or application that first used it: the same key sent by another caller of the tenant is refused with this status, and nothing is rotated. The status follows the IETF Idempotency-Key HTTP header draft (draft 07, §2.7). See Compliance Remediation Plans — retrying safely.

Common Causes

  • A client reused a fixed Idempotency-Key for every request instead of generating one per operation.
  • A retry changed the body (another key list, target or basis) but kept the key.
  • A key rotation was resent for another kid, or with another newMaterial, under the key of an earlier rotation.

Response Example

{
  "type": "https://docs.ankatech.co/errors/idempotency-key-reused",
  "title": "Idempotency Key Reused",
  "status": 422,
  "detail": "This Idempotency-Key was already used for a different request; use a new key for a new request.",
  "instance": "/api/v3/admin/tenants/6f1b2c4e-8a3d-4f7e-9c21-5b0d7e9a1f34/compliance-remediation/NIST_PQC_TRANSITION/actions/NIST.CRYPTOPERIOD/executions",
  "extensions": {
    "requestId": "8b3f0c27-4e1d-4a9b-b6c5-3e7a1d9f2c04"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

How to Resolve

  1. Generate a new UUID for each new operation; reuse a key only to retry the same request unchanged.
  2. To retry a request whose answer was lost, send it again byte for byte with the same key: a finished remediation run answers 200 with the stored execution, without running again, and a key rotation already applied answers 200 with the same body and Idempotent-Replayed: true, without rotating again.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.