Réessayer sans traitement en double
Si vous avez envoyé une requête sans recevoir de réponse, vous devrez peut-être la renvoyer. Ajoutez un identifiant de nouvelle tentative pour permettre au serveur de vérifier si elle a déjà été traitée.
Avec le même identifiant et le même contenu, la nouvelle tentative renvoie le résultat initial sans émettre deux coupons ni créditer deux tampons.
Mode d’emploi
Créez un identifiant unique pour chaque nouvelle opération et transmettez-le dans l’en-tête Idempotency-Key. Réutilisez-le uniquement pour réessayer la même opération si vous n’avez pas reçu de réponse.
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
-H "Authorization: APIKEY {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20260920-000412" \
-d '{
"nm": "$5 discount coupon",
"discTypeIdx": 458,
"disc": 5
}'
Si vous ne pouvez pas envoyer l’en-tête, utilisez le champ requestId dans le corps de la requête. Si vous envoyez les deux, leurs valeurs doivent correspondre.
| Domaines | Description | Type |
|---|---|---|
Idempotency-Key |
En-tête HTTP. Utilisez 8 à 64 caractères : lettres ASCII, chiffres et . _ : -. Choisissez une valeur différente pour chaque nouvelle opération. |
string |
requestId |
Champ du corps de la requête. Il peut remplacer l’en-tête et suit le même format. | string |
Champ d’application
Ce mécanisme concerne la création et l’utilisation de coupons, ainsi que la création, l’ajout et le retrait de tampons et l’utilisation des avantages. Les API v2 de mise à jour des coupons et des tampons acceptent également un identifiant de nouvelle tentative.
L’identifiant est facultatif. Sans lui, la requête est traitée comme auparavant. Les enregistrements sont conservés 72 heures ; passé ce délai, une requête portant la même valeur peut être traitée comme une nouvelle opération.
Les identifiants sont séparés par organisation et par type d’opération. Ne réutilisez pas une valeur pour des opérations différentes au sein de la même organisation.
Réponses et gestion des erreurs
Si vous réessayez une requête déjà réussie avec le même identifiant et le même contenu, le résultat initial est renvoyé. L’opération et le webhook ne sont pas exécutés à nouveau.
En cas de conflit, le statut HTTP est 409 et le champ code du corps vaut aussi 409. Consultez message pour connaître la cause. Même avec HTTP 200, vérifiez que code vaut 0.
| Situation | HTTP | code |
Action à entreprendre |
|---|---|---|---|
| Nouvelle tentative avec le même identifiant et le même contenu | 200 | 0 | Le résultat initial est renvoyé. Aucune autre action n’est nécessaire. |
| Même identifiant utilisé avec un contenu différent | 409 | 409 | Utilisez un nouvel identifiant pour la nouvelle opération. |
| La requête précédente portant le même identifiant est en cours | 409 | 409 | Attendez un instant, puis réessayez avec le même identifiant. |
| Les valeurs de l’en-tête et de requestId diffèrent | 400 | 1213 | Utilisez la même valeur pour les deux ou n’en envoyez qu’un seul. |
| Format de l’identifiant invalide | 400 | 1216 | Utilisez 8 à 64 caractères : lettres ASCII, chiffres ou ces signes : . _ : - |
| Une autre requête a modifié le même élément en premier | 409 | 409 | Vérifiez l’état actuel, puis revoyez votre requête. |
Bonnes pratiques pour réessayer
- Choisissez une valeur, comme un numéro de commande, que vous pourrez réutiliser pour la même opération. Une nouvelle valeur à chaque essai ne permet pas de retrouver la requête précédente.
- Si vous ne recevez pas de réponse, réessayez avec le même identifiant et le même contenu. Si le contenu change, utilisez un nouvel identifiant.
- La réponse à HTTP 409 dépend de la cause. Si le traitement est en cours, réessayez plus tard. En cas de réutilisation de l’identifiant ou de modification concurrente, revoyez la requête.