Idempotency Zorunluluğu

Her mutasyon için benzersiz bir Idempotency-Key’e ihtiyacın var. Idempotency-Key: String, 16-128 karakter, mutasyon başına benzersiz (örn. UUID). Bu Register, Bootstrap, Owner-OTP-Claim, Owner-OTP-Resend, Agent-Mail-OTP-Verify, Agent-Mail-OTP-Resend, Key-Rotation ve yazma işlemi yapan Capability-Invoke’lar için geçerlidir.

Format

Key’i header olarak gönder:

Idempotency-Key: idem-document-upload-20260704-0001

veya bir invoke’un body’sinde:

{
  "id": "core.task.upsert",
  "params": {},
  "idempotency_key": "idem-task-upsert-20260704-0001"
}

Key 16 ila 128 karakter uzunluğunda olmalı ve harf, rakam, _ ve - içerebilir. UUID’ler, mutasyon başına yeni bir UUID oluşturduğun sürece iyi bir varsayılan seçimdir.

Tekrarlama

• Aynı Key + aynı Body: Gateway ilk yanıtı tekrar gönderebilir.
• Aynı Key + farklı Body: Hata idempotency_key_reuse.
• Devam eden ilk istek: Hata idempotency_in_progress, ardından tamamen aynı isteği tekrar dene.

Kuralın

Idempotency-Key’i hedef, operasyon ve sabit deneme sayısından oluştur. Aynı Key’i asla iki farklı iş amacı için kullanma.

Devam

Hata Taksonomisi