Skip to main content
Chaque requête POST authentifiée sur la Current API accepte un en-tête Idempotency-Key. Lorsqu’une requête avec une clé réussit, sa réponse est conservée pendant 24 heures. Une nouvelle tentative avec la même clé renvoie la réponse conservée au lieu d’exécuter à nouveau la requête. Vous pouvez ainsi relancer sans risque une requête qui a expiré ou échoué de votre côté, sans craindre un double débit, un double transfert ou une ressource en double. N’importe quelle chaîne unique de 255 octets maximum peut servir de clé — un UUID est un bon choix par défaut. Générez une nouvelle clé pour chaque opération distincte, et ne réutilisez exactement cette clé que pour relancer cette opération.
Les réponses rejouées sont identiques octet pour octet à l’originale — code de statut compris — et portent un en-tête Idempotent-Replayed: true afin que vous puissiez distinguer une réponse rejouée d’une nouvelle exécution.
Les réponses d’erreur sont aussi rejouées. Si la requête d’origine a échoué avec une erreur 4xx, une nouvelle tentative avec la même clé renvoie cette même erreur. Cet échec était le résultat réel de la requête — envoyez plutôt une nouvelle clé avec la requête corrigée.
Quelques détails à connaître :
  • « Même requête » signifie que la méthode, le chemin, la chaîne de requête, le corps et Api-Version-Date correspondent tous exactement à l’original. Toute différence est considérée comme une réutilisation de clé et rejetée avec une erreur 400 dont le error.code est idempotency_key_mismatch.
  • Les clés sont limitées à l’appelant authentifié. Deux clés API ou utilisateurs différents peuvent utiliser la même valeur de clé sans conflit.
  • L’en-tête est ignoré sur les requêtes non authentifiées et sur les méthodes autres que POST — les requêtes GET, PATCH et DELETE peuvent être relancées sans risque.
  • Tant que la première requête avec une clé est en cours, une nouvelle tentative renvoie une erreur 409 dont le error.code est idempotency_request_in_progress. Si la première requête a échoué avec un résultat inconnu (par exemple, une panne du serveur en cours de requête), les nouvelles tentatives continuent de renvoyer cette erreur 409 jusqu’à l’expiration de la clé. L’API ne prend jamais le risque d’exécuter une requête deux fois.