Gestion des échecs et des nouvelles tentatives

Audience

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

L'API Partnerships est conçue pour la sécurité de réessai. Trois primitives portent le contrat :

Idempotency-Key (en-tête de requête que vous envoyez) : réduit les réessais à une seule opération côté serveur. Requis pour chaque écriture. Le serveur met en cache la réponse pendant 24 heures ; après cela, la clé expire.
X-Operation-Id (en-tête de réponse que le serveur renvoie) : identifiant durable pour l'enregistrement de l'opération. Utilisez-le avec GET /v1/partnership/operations/{operation_id} pour récupérer après des échecs réseau.
request_id (champ sur chaque enveloppe de réponse ; également renvoyé dans l'en-tête de réponse X-Request-Id) : ID de trace pour une seule tentative. Transmettez-le au support lorsque vous déposez un ticket.

remarque

Chaque réponse est enveloppée. Les réponses de succès et d'erreur reviennent sous forme de { status, error, message, request_id, data }. Les exemples ci-dessous montrent l'enveloppe complète afin que la logique de réessai qui inspecte request_id ou error corresponde à ce que le serveur émet réellement.

Utilisez-les correctement et les réessais sont gratuits.

Scénario d'échec 1 : Délai d'attente réseau avant la réponseLien direct vers Scénario d'échec 1 : Délai d'attente réseau avant la réponse

Vous avez envoyé la requête, mais la connexion a échoué avant que vous ne receviez une réponse. Le serveur peut avoir validé la modification, ou peut-être pas. Vous ne savez pas.

Résolution :

Si vous avez capturé X-Operation-Id à partir de toute réponse partielle, interrogez directement l'opération :
```
curl https://accounts.rokt.com/v1/partnership/operations/$OPERATION_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"
```
data.status est l'un des pending / in_progress / completed / failed. Si completed, data.response_body contient la charge utile de la réponse de l'écriture originale. Si failed, data.error est le dernier message d'erreur capturé.
Si vous n'avez pas de X-Operation-Id, réessayez l'appel original avec le même Idempotency-Key. Dans la fenêtre de déduplication de 24 heures, le serveur renvoie la réponse mise en cache si l'original a réussi, ou réexécute s'il a échoué.

Scénario d'échec 2 : 5xx de RoktLien direct vers Scénario d'échec 2 : 5xx de Rokt

Erreur transitoire côté serveur. Attendez, réessayez, même clé.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $SAME_KEY_AS_BEFORE" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Si vous recevez toujours 5xx après 3 réessais avec un backoff exponentiel, capturez request_id à chaque tentative et déposez un ticket de support. Ne continuez pas à insister ; reculez et escaladez.

Scénario d'échec 3 : Erreur de validation 400Lien direct vers Scénario d'échec 3 : Erreur de validation 400

Votre charge utile est incorrecte. Le champ message de l'enveloppe décrit le paramètre fautif ; request_id est l'ID de trace.

{
  "status": 400,
  "error": "BadRequest",
  "message": "no partnership vertical mapping for partnerVerticalId=1500 partnerSubVerticalId=9999",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": null
}

Corrigez la charge utile et soumettez à nouveau avec une NOUVELLE Idempotency-Key. L'ancienne clé est maintenant mise en cache comme une opération échouée ; la réutiliser dans la fenêtre de 24 heures renvoie le 400 mis en cache.

Scénario d'échec 4 : 401 / 403 / 422Lien direct vers Scénario d'échec 4 : 401 / 403 / 422

401 Non autorisé : Le jeton API est manquant, mal formé ou expiré. Faites tourner le jeton via votre intégration d'émission de jeton et réessayez. Voir Authentification.

403 Interdit : Votre jeton API est valide mais vous n'avez pas la subvention de relation gérée par le gestionnaire sur ce compte, ou X-Platform-Parent-Account-Id ne correspond pas au parent réel du compte géré. Soit :

La relation a été révoquée (le marchand a été retiré de votre plateforme côté Rokt).
Le compte appartient à une autre plateforme partenaire.
Vous avez envoyé la mauvaise valeur X-Platform-Parent-Account-Id.

Signalez cela à votre équipe des opérations. Ne réessayez pas ; 403 est structurel, pas transitoire.

422 Non traitable : Un en-tête requis est manquant. Le plus souvent, l'en-tête X-Platform-Parent-Account-Id lors d'un appel d'écriture. Ajoutez l'en-tête et réessayez.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
  -H "Authorization: Bearer $NEW_API_TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Scénario d'échec 5 : Conflit 409Lien direct vers Scénario d'échec 5 : Conflit 409

Deux significations distinctes :

Sur register/partnership : une autre plateforme partenaire possède déjà cet store_identifier. L'URL de la vitrine du marchand a été enregistrée via une autre plateforme en premier.

{
  "status": 409,
  "error": "Conflict",
  "message": "Rokt Account already exists",
  "request_id": "0e3a1b9c-...",
  "data": null
}

Présentez ce message au marchand tel quel :

Il y a un problème avec la création du compte qui nécessite un examen plus approfondi. Veuillez envoyer un e-mail au support de la plateforme partenaire.

Ne réessayez pas l'enregistrement. Le chemin de résolution inter-partenaires est manuel.

Sur les points de terminaison d'écriture (contrôles, statut) : vous avez réutilisé une Idempotency-Key d'une opération encore en cours avec un corps de requête différent. Soit :

Attendez un peu et réessayez ; certains chemins traitent de manière asynchrone.
Générez une nouvelle Idempotency-Key et réessayez. Cela démarre une nouvelle opération.

Scénario d'échec 6 : Opération bloquée en `in_progress`Lien direct vers failure-scenario-6-operation-stuck-in-in_progress

Votre écriture a retourné 202 Accepted (ou s'est terminée de manière synchrone) et vous a donné un X-Operation-Id. Vous avez sondé GET /v1/partnership/operations/{operation_id} et data.status est toujours in_progress bien au-delà de la latence que vous attendriez pour ce point de terminaison (par exemple > 60s pour le statut / contrôles, > 5 min pour l'enregistrement). L'opération n'a atteint ni completed ni failed.

Comment détecter :

data.status === "in_progress" à chaque sondage pendant une période prolongée.
Aucun mouvement dans data.updated_at à travers des sondages consécutifs ; l'enregistrement de l'opération n'est pas touché.
data.attempts (si présent) n'augmente pas ; aucun travailleur asynchrone ne le prend en charge.

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": {
    "operation_id": "op_3a1b9c...",
    "status": "in_progress",
    "updated_at": "2026-05-20T19:14:00Z",
    "response_body": null,
    "error": null
  }
}

Résolution : escalader, ne PAS réessayer l'écriture originale. Déposez un ticket de support avec :

Le X-Operation-Id bloqué.
La Idempotency-Key que vous avez envoyée.
Le request_id original de la réponse d'écriture.
Le point de terminaison et une charge utile assainie.

Pourquoi réessayer est dangereux. Une opération bloquée en in_progress a presque certainement un état partiellement engagé : au moins une étape de provisionnement a été exécutée, et le travailleur est soit en panne, soit en pause, soit bloqué sur une ressource en aval. Réenvoyer l'écriture originale avec une nouvelle Idempotency-Key crée une deuxième opération qui entre en concurrence avec la première. Selon le point de terminaison, cela peut produire :

Des enregistrements en double (si l'engagement original a eu lieu mais que la projection post-engagement ne l'a pas fait).
Des états de contrôles de marché en conflit.
Une cascade de statuts qui entre en conflit avec celle en cours et laisse des variantes en mixed.
Une deuxième session Stripe Connect pour le même marchand.

Réenvoyer avec la même Idempotency-Key ne servira à rien non plus : la clé est déjà liée à l'opération bloquée et le serveur court-circuitera à "opération en cours" (409). La seule solution sûre est l'escalade : le support dispose du manuel pour soit reprendre l'opération existante, soit la marquer failed proprement afin que vous puissiez réessayer à partir d'un état connu.

Politique de réessai recommandéeLien direct vers Politique de réessai recommandée

Recul exponentiel avec gigue : 5 tentatives max

Tentative 1 : immédiate
Tentative 2 : attendre 1s ± gigue
Tentative 3 : attendre 2s ± gigue
Tentative 4 : attendre 4s ± gigue
Tentative 5 : attendre 8s ± gigue
Abandonner après la tentative 5, escalader au support avec tous les request_ids

import time, random, requests

def put_with_retry(url, body, token, parent, idem_key, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.put(
            url,
            headers={
                "Authorization": f"Bearer {token}",
                "X-Platform-Parent-Account-Id": parent,
                "Idempotency-Key": idem_key,  # same key across retries
                "Content-Type": "application/json",
            },
            json=body,
        )
        if r.status_code < 500 and r.status_code != 408:
            return r  # success, 4xx (don't retry), or done
        time.sleep((2 ** attempt) + random.random())
    raise RuntimeError(
        f"exhausted retries; last request_id={r.json().get('request_id')}"
    )

Règles empiriques

Toujours réutiliser Idempotency-Key à travers les réessais de la même opération logique dans la fenêtre de déduplication de 24h. Laissez le serveur les effondrer.
Toujours générer une nouvelle Idempotency-Key après un 400. L'ancienne clé est empoisonnée pour le reste de la fenêtre de 24h.
Toujours enregistrer request_id par tentative. C'est l'ID de trace dont le support a besoin.
Ne jamais réessayer 401/403. Ce sont des échecs structurels.
422 signifie que vous avez oublié un en-tête requis. Ajoutez-le, réessayez avec la même clé.
Ne jamais réessayer 409 sur register/partnership. Présentez-le au marchand.
Pour les délais d'attente, préférez le sondage de X-Operation-Id à un réessai aveugle si vous avez capturé l'en-tête ; c'est moins coûteux et révèle le résultat original.

Idempotency Keys

Comment le serveur gère les tentatives de nouvelle connexion et combien de temps les clés sont mises en cache.

Dry-Run Mode

Valider une charge utile de bout en bout avant de l'engager réellement.