Idempotence

Idempotency-Key: cmd-184-tentative-1

┌─ 2xx ──────────── succès, ne réessayez pas
│
├─ 400, 402, 403, 422 ── refus concluant : corrigez la requête,
│                        ne réessayez pas tel quel
│
├─ 409 IDEMPOTENT_REQUEST_IN_FLIGHT ── même clé, dans quelques secondes
│
├─ 409 IDEMPOTENCY_KEY_REUSED ──────── bug : votre clé n'est pas unique
│
├─ 429 ───────────────────── même clé, après une pause
│
└─ 503, 504 ─────────────── même clé : l'issue est inconnue,
                            l'opération a peut-être été enregistrée

{
  "success": false,
  "error": {
    "code": "DUPLICATE_EXTERNAL_REFERENCE",
    "message": "Cette référence externe a déjà été utilisée pour une autre opération.",
    "details": {
      "externalReference": "CMD-2026-00184",
      "existingOperation": "GUI-CI-20261001-7K2M9QX4",
      "existingStatus": "SUCCEEDED"
    }
  }
}

// La clé est dérivée de la commande : stable à travers les tentatives,
// unique entre les commandes.
const idempotencyKey = `cashin-${order.id}`;

async function encaisser(order, tentative = 1) {
  const response = await fetch('https://guichet.apidjonanko.tech/v1/cashin', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DJONANKO_GUICHET_KEY,
      'x-api-secret': process.env.DJONANKO_GUICHET_SECRET,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: order.amount,
      country: 'CI',
      operator: order.operator,
      payerPhone: order.phone,
      externalReference: order.id,
    }),
  });

  // 200 comme 201 sont des succès : 200 signifie simplement que cette clé
  // avait déjà été traitée et que la réponse initiale est rejouée.
  if (response.ok) return response.json();

  const body = await response.json();

  // Issue inconnue : on réessaie, avec la même clé.
  const aRejouer = [409, 429, 503, 504].includes(response.status);
  if (aRejouer && tentative < 4) {
    await new Promise((r) => setTimeout(r, 2000 * 2 ** (tentative - 1)));
    return encaisser(order, tentative + 1);
  }

  throw new Error(`${body.error.code} — requestId ${body.requestId}`);
}