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.

Request
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 2000 Le résultat initial est renvoyé. Aucune autre action n’est nécessaire.
Même identifiant utilisé avec un contenu différent 409409 Utilisez un nouvel identifiant pour la nouvelle opération.
La requête précédente portant le même identifiant est en cours 409409 Attendez un instant, puis réessayez avec le même identifiant.
Les valeurs de l’en-tête et de requestId diffèrent 4001213 Utilisez la même valeur pour les deux ou n’en envoyez qu’un seul.
Format de l’identifiant invalide 4001216 Utilisez 8 à 64 caractères : lettres ASCII, chiffres ou ces signes : . _ : -
Une autre requête a modifié le même élément en premier 409409 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.