Idempotence

Réessayez sans risque : une même requête ne s’exécute jamais deux fois.

Une erreur réseau ne dit pas si votre requête est arrivée chez Monerail. Rejouer un paiement à l’aveugle pourrait payer deux fois. Pour l’éviter, envoyez un en-tête Idempotency-Key sur chaque POST :

curl https://api.monerail.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: payout-inv-118" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150000, "currency": "XAF", "recipient": {"type": "mobile_money", "name": "Kossi Mensah", "phone": "237670000777", "operator": "MTN"}}'

Fonctionnement#

• La première requête avec une clé s’exécute normalement. Monerail garde son code et sa réponse pendant 24 heures.
• Une requête ultérieure avec la même clé, sur le même point d’accès, avec le même corps (à l’octet près) renvoie la réponse gardée, sans s’exécuter à nouveau, avec l’en-tête Idempotent-Replayed: true. Les erreurs 4xx sont gardées et rejouées elles aussi.
• La même clé avec un autre corps, ou sur un autre point d’accès, échoue avec 422 idempotency_key_reused.
• Si la première requête est encore en cours, une seconde échoue avec 409 idempotency_key_in_use. Patientez un instant et réessayez.
• Une erreur 5xx n’est pas gardée : réessayer avec la même clé exécute à nouveau la requête. Monerail ne répond 5xx que si aucun argent n’est parti. Si un problème survient après l’envoi de l’opération à un partenaire de paiement ou à l’émetteur de cartes, vous recevez à la place 202 avec l’objet (processing ou pending), et ce 202 est gardé : une nouvelle tentative le rejoue et n’envoie jamais l’argent deux fois.
• Une création de point de terminaison rejouée renvoie le point de terminaison sans son secret, présent seulement dans la réponse d’origine.

Les clés sont propres à votre entreprise et à votre mode, 255 caractères au plus. Prenez une valeur liée à l’opération dans votre système (payout-inv-118) ou un UUID que vous enregistrez avec elle. Les requêtes GET et DELETE n’en ont pas besoin.

Quand réessayer#