Erreurs et idempotence — API/SDK avancé
Décidez ce qui doit être retenté, ce qui exige une intervention et comment éviter les doublons financiers dans les intégrations API/SDK avancées.
Mis à jour le August 3, 2026
Ces règles d’erreur, de nouvelle tentative et d’idempotence s’appliquent aux requêtes API/SDK avancées. Les livraisons Stripe connectées de Stripe automatique sont reçues durablement, vérifiées, contrôlées selon le mode, retentées et traitées par AffiHQ ; les marchands ne doivent pas construire de boîte d’envoi AffiHQ ni dupliquer ces événements via l’API. Utilisez le statut de la réponse et le code d’erreur pour choisir entre une nouvelle tentative avec le message d’origine et un examen manuel.
Erreurs temporaires
En mode API/SDK avancé, les erreurs réseau, délais dépassés, réponses 429, réponses 5xx et réponses amont illisibles peuvent être retentés. Conservez le message d’origine dans la boîte d’envoi ainsi que l’identité de l’événement, puis appliquez un délai exponentiel avec une part aléatoire.
Le client ne doit pas attendre pendant ces nouvelles tentatives.
Erreurs définitives
En mode API/SDK avancé, une donnée invalide, une référence inconnue ou une référence non admissible exige une correction du code ou une intervention humaine. Placez le message dans un état de rejet visible avec son code d’erreur sans donnée sensible et son identifiant de requête.
Ne modifiez pas automatiquement un montant, une devise, un affilié ou une identité client rejetés. Conservez les données d’origine et le code d’erreur pour vérifier la correction avant un nouvel envoi.
Idempotence métier du mode API/SDK avancé
Un événement de facturation est unique par produit, prestataire et identifiant d’événement prestataire. Un rejeu identique renvoie un succès avec duplicate: true. La même identité accompagnée de données différentes renvoie idempotency_conflict.
La création d’attribution peut aussi être rejouée sans risque. La première attribution admissible d’un produit et d’un client reste la référence, puis une requête identique renvoie created: false.
Indicateurs d’exploitation
Pour le mode API/SDK avancé, surveillez la taille de la file, l’âge du plus ancien message, le nombre de tentatives et les rejets définitifs. Distinguez dans les alertes une indisponibilité temporaire d’AffiHQ et une erreur d’intégration définitive : elles n’appellent pas la même réponse.