Clés d'Idempotence

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des placements sur leur propre processus de paiement devraient utiliser les documents de développement Rokt Ecommerce à la place.

Chaque appel d'écriture à l'API Partnerships nécessite un en-tête Idempotency-Key. Le serveur stocke (parent_account_id, account_id, idempotency_key) comme une contrainte UNIQUE et renvoie la réponse mise en cache du premier appel pour la durée de la fenêtre de cache. Utilisez un UUID frais par opération logique ; réessayez en renvoyant la même clé.

Contrat

• L'en-tête est requis pour chaque écriture. Son absence renvoie 400.
• Le format est UUID. Utilisez n'importe quelle variante RFC 4122 ; UUIDv4 convient. Choisissez quelque chose de haute entropie ; ne réutilisez jamais une clé pour une écriture logique différente.
• La portée est par compte géré. La même clé sur deux account_ids différents ne se chevauche pas.
• TTL est d'environ 24 heures. Correspond à la fenêtre de rétention du cache d'idempotence. Après expiration, la même clé est traitée comme une nouvelle demande.

Hygiène des clés

Traitez Idempotency-Key comme un jeton de déduplication côté serveur, pas comme des données :

• Une clé par écriture logique. Une nouvelle tentative de la même écriture logique réutilise la même clé, mais une nouvelle opération marchande obtient une nouvelle clé.
• N'intégrez jamais de PII (email, nom, ID de commande) dans la clé. Les clés apparaissent dans les journaux du serveur et les pistes d'audit.
• Les clés ne sont pas secrètes, mais elles ne sont pas non plus une autorisation : la possession d'une clé ne donne pas accès à une écriture. Le jeton + account_id contrôlent toujours l'appel.
• Ne réutilisez pas les clés sur différents points de terminaison ou différents account_ids, même si la protection de portée le rend sûr. Mélanger les portées rend votre propre journal de réessai plus difficile à déboguer.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @mcl.json

Même clé, corps différent

Si vous réutilisez une clé avec un corps différent, le serveur renvoie la réponse du premier appel ; il ne traite pas à nouveau avec le nouveau corps. C'est intentionnel : Idempotency-Key réduit les tentatives, il ne versionne pas les modifications.

attention

Modifier une charge utile et la renvoyer sous la même clé est silencieusement ignoré. Si vous voulez qu'une nouvelle écriture prenne effet, utilisez une nouvelle clé.

Tableau des résultats

Scénario	HTTP	Ce qui est retourné
Premier appel	200 / 201	Réponse fraîche
Réessayer, original complété	200 / 201	Réponse mise en cache (corps identique en octets)
Réessayer, original échoué de manière transitoire	correspond à l'échec original	Échec mis en cache ; le serveur réessaye jusqu'à 3 fois en interne
Réessayer, original échoué avec 4xx	correspond à l'échec original	Échec mis en cache ; pas de réessai interne (le client doit corriger la charge utile + utiliser une nouvelle clé)
Même clé, même corps, après 24h TTL	200 / 201	Traité comme une nouvelle demande ; une nouvelle écriture s'exécute. La réponse originale n'est plus mise en cache.
En-tête Idempotency-Key manquant	400	Enveloppe d'erreur ci-dessous
Même clé en cours, corps différent	409	Enveloppe d'erreur IdempotencyConflict

L'enveloppe d'erreur pour une clé manquante :

{
  "error": "Idempotency-Key header is required",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2"
}

Démonstration : réessayer avec la même clé

C'est le modèle de réessai recommandé. Générez la clé une fois, stockez-la localement, envoyez-la à chaque réessai.

1. 1
   Generate and persist the key

   IDEM_KEY=$(uuidgen)
   echo "$IDEM_KEY" > /tmp/last-mcl-key

2. 2
   First call: server processes, returns 200

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $IDEM_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Network Controls","blockedVerticals":[{"partnerVerticalId":1500,"partnerSubVerticalId":1610,"policy":"Block"}]}'

   Réponse : 200 avec le nouveau marketplace_controls_list_id et content_hash.

3. 3
   Network blip: your client never sees the response

   Votre client HTTP lance un timeout. Vous ne savez pas si le serveur a traité l'écriture.

4. 4
   Replay with the same key

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "Idempotency-Key: $(cat /tmp/last-mcl-key)" \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Network Controls","blockedVerticals":[{"partnerVerticalId":1500,"partnerSubVerticalId":1610,"policy":"Block"}]}'

   Réponse : 200 avec le même marketplace_controls_list_id et content_hash que l'étape 2. Sûr : aucune écriture en double n'a eu lieu.

Quand le réseau a mangé la réponse, préférez le sondage de l'opération

La relecture de la clé d'idempotence (Idempotency-Key) fonctionne, mais elle relance le corps de la requête à travers la validation à chaque fois. Si vous avez capturé X-Operation-Id à partir des en-têtes de réponse originaux (ou si votre client l'a enregistré avant l'expiration du délai), le sondage de l'opération récupère directement la réponse sans revalider le corps.

Connexes

Operation Polling

Récupérer des expirations de délai en utilisant X-Operation-Id.

Dry-Run Mode

Les tests à blanc consomment toujours des clés d'idempotence.