idempotency_key_format

HTTP status: 400

On /v3/* endpoints, the Idempotency-Key header must be a UUID v4. The header you sent was rejected at the edge before your operation ran.

Why this happens

• The key was a job ID, slug, or other application-domain string.
• The key was derived from a hash of the request body (forbidden — two distinct requests can hash identically and collide).
• A UUID of a different version (v1/v5) or a malformed UUID string was sent.

On v2 endpoints, any string is accepted for backward compatibility. Responses include a Deprecation header to help you spot non-conforming callers before migrating to v3.

What to do

1. Mint the key with the platform UUID library: crypto.randomUUID(), uuid.uuid4(), google/uuid, Guid.NewGuid(), or Str::uuid().
2. Reuse that one key across every retry of the same operation; never derive it from the body.
3. The SDKs mint UUID v4 automatically. You only see this error when calling the API directly or overriding the key manually.

Example response

{
  "type": "https://zyins.isaapi.com/errors/idempotency-key-format",
  "title": "Idempotency-Key must be a UUID v4",
  "status": 400,
  "detail": "Received \"job-2026-05-28-7421\"; expected a UUID v4 (e.g. 550e8400-e29b-41d4-a716-446655440000).",
  "code": "idempotency_key_format",
  "param": null,
  "request_id": "req_01HZK2N5GQR9T8X4B6FJW3Y1AS"
}

SDK exceptions

See also

• Error catalog
• Idempotency guide