Idempotency-Key

Une clé d’idempotence vous permet de relancer une requête POST sans risquer d’exécuter le travail deux fois. Si une erreur réseau, un timeout ou un crash vous laisse incertain quant à la bonne réception de votre requête par Meetingize, renvoyez-la avec la même clé : vous récupérez la réponse d’origine au lieu d’une deuxième réunion, d’un deuxième document ou d’une deuxième facturation.

Comment l’utiliser ?

Ajoutez un en-tête Idempotency-Key à toute requête POST. Utilisez une valeur unique par opération, typiquement un UUID v4 généré au moment où vous décidez d’effectuer l’action (pas au moment où vous envoyez la requête) :

KEY=$(uuidgen)
curl -s -X POST "https://app.meetingize.com/api/v1/meetings/$MEETING_ID/documents" \
  -H "Authorization: Bearer $MEETINGIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"template_id": "tpl_42"}'
# Erreur réseau ? Renvoyez exactement la même requête avec la même $KEY.

Stockez la clé avec l’opération dans votre système (par exemple sur l’enregistrement du CRM qui l’a déclenchée) afin qu’une relance après un redémarrage la réutilise.

Que se passe-t-il si je relance ?

Situation	Réponse
Première requête avec cette clé	traitée normalement
Même clé, même corps, première requête terminée	la réponse d’origine est rejouée (même statut, même corps), avec l’en-tête Idempotent-Replayed: true. Rien n’est réexécuté ni refacturé
Même clé, même corps, première requête encore en cours	409 idempotency_key_in_use : patientez un instant et relancez
Même clé, corps différent	422 idempotency_key_reused : une clé identifie une opération, générez-en une nouvelle pour une nouvelle opération

Pour les envois multipart, la comparaison porte sur les champs du formulaire et le fichier envoyé (nom, taille et SHA-256), si bien que le même fichier avec la même clé est reconnu comme une relance.

Bon à savoir

• Les clés sont conservées 24 heures. Passé ce délai, la même clé est traitée comme une nouvelle opération.
• Les clés sont propres à votre compte : deux comptes ne peuvent pas entrer en collision.
• Les requêtes GET sont naturellement sûres à relancer et ignorent cet en-tête.
• Toute chaîne de 255 caractères maximum fonctionne ; les UUID sont recommandés.
• Le serveur MCP envoie une clé d’idempotence sur chaque action d’écriture confirmée, dérivée de l’action et de ses arguments, afin qu’un assistant IA qui relance un appel d’outil ne démarre jamais le même job deux fois.