Idempotence

Sur un réseau, une requête peut échouer sans que vous sachiez si le serveur l'a traitée. Vous tentez alors un nouvel envoi, mais comment garantir qu'un transfert ne sera pas créé deux fois ? L'idempotence répond à cette question. En joignant un en-tête Idempotency-Key à vos appels d'écriture, vous indiquez à l'API Coffrify que plusieurs requêtes portant la même clé doivent produire un seul et même résultat. La première requête est exécutée et son résultat mémorisé ; les suivantes renvoient ce résultat enregistré, sans rien recréer.

Quand l'utiliser

L'idempotence concerne les opérations d'écriture, c'est-à-dire les requêtes POST et DELETE qui modifient l'état de votre espace de travail : création d'un transfert, d'une réception ou d'un webhook par exemple. Les lectures (GET) sont par nature sans effet de bord et n'ont pas besoin de clé. Nous vous recommandons d'envoyer une clé d'idempotence sur toutes vos écritures, en particulier celles qui s'exécutent automatiquement dans un script, une file d'attente ou une tâche planifiée, là où un nouvel essai peut survenir sans intervention humaine.

L'en-tête Idempotency-Key

Pour rendre une requête idempotente, ajoutez l'en-tête Idempotency-Key avec une valeur unique que vous générez vous-même. Cette valeur doit comporter entre 8 et 255 caractères. Un identifiant aléatoire de type UUID v4 constitue un excellent choix, car il est pratiquement impossible qu'il entre en collision avec une autre opération.

curl https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1f8d4c2a-9b3e-4f6a-8c1d-2e7f0a9b5c3d" \
  -d '{
    "files": [{"name": "contrat.pdf", "size": 248113, "mime_type": "application/pdf"}],
    "transfer_title": "Contrat signé"
  }'

Comment fonctionne le rejeu

Lorsque l'API reçoit une clé qu'elle a déjà vue, elle ne réexécute pas l'opération. Elle renvoie la réponse mémorisée lors du premier appel, avec le même corps et le même code de statut. Pour que vous puissiez distinguer un traitement initial d'un rejeu, la réponse rejouée porte l'en-tête X-Coffrify-Idempotent-Replay: true. Votre code peut s'appuyer sur cet en-tête pour, par exemple, éviter de notifier deux fois un utilisateur.

$ # Premier appel : le transfert est créé
$ curl -i https://api.coffrify.com/v1/transfers -H "Idempotency-Key: cmd-2026-06-10-001" ...
HTTP/2 201
 
$ # Second appel avec la même clé : réponse rejouée à l'identique
$ curl -i https://api.coffrify.com/v1/transfers -H "Idempotency-Key: cmd-2026-06-10-001" ...
HTTP/2 201
X-Coffrify-Idempotent-Replay: true

Même clé, corps différent : le conflit 409

Une clé d'idempotence est liée au contenu de la requête qui l'a créée. Si vous réutilisez une clé déjà employée mais que vous changez le corps de la requête, l'API ne peut pas savoir laquelle des deux intentions honorer. Elle refuse alors l'appel avec un code de statut 409 et l'erreur idempotency_conflict. C'est une protection : elle vous évite d'écraser silencieusement une opération par une autre.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Cette clé d'idempotence a déjà été utilisée avec un corps de requête différent.",
    "request_id": "req_8a2f1c9d4b"
  }
}

Articulation avec les nouveaux essais

L'idempotence prend tout son sens combinée à une logique de réessai. La règle est simple : générez la clé avant d'entrer dans votre boucle de réessai, puis conservez la même clé pour chacune des tentatives. Ainsi, que la première requête ait échoué avant ou après son traitement par le serveur, les tentatives suivantes aboutiront au même résultat unique. Réessayez de préférence sur les erreurs réseau, les délais d'attente dépassés et les réponses 429 (limite de débit) ou 5xx, en espaçant les tentatives de façon croissante.

import { Coffrify } from "coffrify";
import { randomUUID } from "node:crypto";
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
// La clé est générée une seule fois, hors de la boucle
const idempotencyKey = randomUUID();
 
async function creerTransfert() {
  for (let tentative = 0; tentative < 4; tentative++) {
    try {
      return await coffrify.transfers.create(
        {
          files: [{ name: "contrat.pdf", size: 248113, mime_type: "application/pdf" }],
          transfer_title: "Contrat signé",
        },
        { idempotencyKey }
      );
    } catch (err) {
      if (tentative === 3) throw err;
      // Patiente avant de rejouer avec la MÊME clé
      await new Promise((r) => setTimeout(r, 2 ** tentative * 500));
    }
  }
}

En-têtes et codes en un coup d'œil

Bonnes pratiques

• Générez la clé avec un générateur aléatoire fiable, par exemple un UUID v4, et restez dans la plage de 8 à 255 caractères.
• Créez la clé en amont de toute logique de réessai, puis réutilisez-la sans la modifier pour chaque tentative de la même opération.
• Envoyez une clé sur toutes vos écritures, surtout celles déclenchées par des automatismes ou des files d'attente.
• Inspectez l'en-tête X-Coffrify-Idempotent-Replay pour éviter de déclencher deux fois une action en aval (e-mail, notification).
• Si vous obtenez un 409 idempotency_conflict, ne réutilisez pas la clé : générez-en une nouvelle pour la nouvelle intention.