Idempotence obligatoire

Chaque mutation exige une clé Idempotency-Key unique. Il s’agit d’une chaîne de 16 à 128 caractères, propre à la mutation, par exemple un UUID. Cette règle s’applique à Register, Bootstrap, Owner-OTP-Claim, Owner-OTP-Resend, Agent-Mail-OTP-Verify, Agent-Mail-OTP-Resend, à la rotation des clés et aux appels de capacités en écriture.

Format

Envoyez la clé dans un en-tête :

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

ou dans le corps d’un appel invoke :

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

La clé doit comporter de 16 à 128 caractères et peut contenir des lettres, des chiffres, _ et -. Les UUID constituent un choix adapté si vous en créez un nouveau pour chaque mutation.

Répéter un appel

• Même clé et même corps : la passerelle peut renvoyer la première réponse.
• Même clé et corps différent : erreur idempotency_key_reuse.
• Première requête encore en cours : erreur idempotency_in_progress. Réessayez ensuite exactement la même requête.

Règle à suivre

Associez la clé d’idempotence à la cible, à l’opération et à une tentative stable. Ne réutilisez jamais une clé pour deux intentions métier différentes.

Pour continuer

Catégories d’erreurs