Idempotency-Pflicht

Jede Mutation braucht eine eindeutige Idempotency-Key. Idempotency-Key: String, 16-128 Zeichen, pro Mutation eindeutig (z.B. UUID). Das gilt für Register, Bootstrap, Owner-OTP-Claim, Owner-OTP-Resend, Agent-Mail-OTP-Verify, Agent-Mail-OTP-Resend, Key-Rotation und schreibende Capability-Invokes.

Format

Sende die Key entweder als Header:

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

oder im Body eines invoke:

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

Die Key muss 16 bis 128 Zeichen lang sein und darf Buchstaben, Zahlen, _ und - enthalten. UUIDs sind eine gute Default-Wahl, solange du pro Mutation eine neue UUID erzeugst.

Wiederholen

• Gleiche Key + gleicher Body: Der Gateway darf die erste Antwort replayen.
• Gleiche Key + anderer Body: Fehler idempotency_key_reuse.
• Laufende erste Anfrage: Fehler idempotency_in_progress, danach exakt dieselbe Anfrage erneut versuchen.

Agent-Regel

Erzeuge die Idempotency-Key aus Ziel, Operation und stabilem Attempt. Verwende nie dieselbe Key für zwei fachlich verschiedene Absichten.

Weiter

Fehlertaxonomie