Poste de travail technique pour préparer un catalogue

Intégration et exploitation · Fiche de contrôle

Contrôler une erreur API et sa reprise

À utiliser lorsqu’une demande fournisseur échoue, est limitée ou reste sans résultat certain. Distinguer la cause observée et l’effet possible de l’opération avant une reprise.

Publié le . Mise à jour éditoriale le . Méthode éditoriale à adapter à votre produit et à votre organisation. Source de référence : RFC 6585 : statut 429, consultée le .

Définir ce que la fiche doit permettre de vérifier

À utiliser lorsqu’une demande fournisseur échoue, est limitée ou reste sans résultat certain. Distinguer la cause observée et l’effet possible de l’opération avant une reprise.

Adapter les contrôles au produit utilisé et conserver les résultats sur un échantillon autorisé, sans effectuer d’opération réelle inutile.

Une création acceptée peut encore être en cours. Dans le cas documenté par Duffel, une réponse 202 à la création ne doit pas déclencher une seconde commande. Le guide de gestion des incidents distingue ce cas des informations encore incomplètes après un 200 et d’une ressource créée en 201.

Mise en pratique · situation fictive

Quel résultat cette fiche doit-elle permettre de vérifier ?

Les données et conditions de cet exercice sont inventées. Rejouez le cas dans un environnement autorisé en utilisant les huit contrôles de la fiche, puis comparez votre lecture au résultat proposé.

Situation de départ

À 10 h, une recherche fictive reçoit 429 avec Retry-After de trente secondes. L’offre précédemment affichée expire à 10 h 00 min 20 s. À 10 h 00 min 30 s, la reprise est autorisée mais l’ancienne offre a dépassé sa durée ; aucun engagement n’a encore été pris.

Comparer avec le résultat attendu

Respecter les trente secondes sans conserver l’ancienne offre comme réservable. À la reprise, rechercher une offre courante et refaire les contrôles de prix et capacité avant engagement. Le 429 n’établit ni disponibilité ni indisponibilité ; son délai dépasse ici de dix secondes la validité de l’offre précédente.

Huit champs à rapprocher de leurs preuves

Gardez la source et la date de vérification à côté des informations collectées. Sur téléphone, les contrôles se lisent en cartes.

Contrôler une erreur API et sa reprise : données et contrôles
ChampÀ collecterTest ou rapprochement
IntentionRecherche, lecture ou création et dossier concerné.Identifier les effets possibles avant de répéter l’action.
ObservationStatut HTTP, code métier et heure.Garder séparés transport, refus métier et résultat inconnu.
CorrélationRéférence de tentative et identifiants déjà obtenus.Retrouver la première demande avant d’en créer une autre.
Limite429 à 10 h avec Retry-After de trente secondes.Programmer la reprise selon le contrat et limiter les tentatives, sans boucle immédiate.
ValiditéAncienne offre valable seulement jusqu’à 10 h 00 min 20 s.Constater son expiration avant la reprise à 10 h 00 min 30 s et obtenir une offre courante.
RépétitionGarantie documentée et contenu identique.Ne pas inventer une nouvelle clé pour contourner l’incertitude.
LectureÉtat fournisseur recherché et preuve obtenue.Rapprocher le résultat avant une nouvelle transaction.
ArrêtPlusieurs limitations successives empêchent une recherche actuelle.Prévoir un arrêt attribué et un message d’indisponibilité de recherche, sans annoncer le stock épuisé.

Trois erreurs qui fragilisent le dossier

  • Traiter un délai dépassé comme une absence certaine de commande.
  • Relancer toutes les demandes au même instant après une limite.
  • Dépasser la validité de l’offre sans nouvelle lecture.

Transmettre un résultat exploitable

Transmettre source, références, observations, décisions et tâches ouvertes. Nommer la prochaine action, son responsable et son échéance plutôt que de fermer un dossier dont le résultat reste incertain.

Choisir un registre de contenus, médias ou recette · Préciser les responsabilités du parcours

Questions fréquentes

Quand arrêter une reprise automatique ?

À l’échéance ou au plafond défini, ou quand l’opération reste incertaine et exige une lecture ou une intervention.

Quelle équipe doit recevoir un refus de permission ?

Le circuit qui gère les droits ou le contrat du compte ; répéter la même demande ne modifie pas son autorisation.

Que conserver pour retrouver une tentative ?

Intention, contenu pertinent, horodatage, corrélation, références et résultats observés, sans multiplier les copies de données sensibles.

Documentation et application

Les précisions utiles des sources

Stripe : distinguer les règles d’idempotence v1 et v2

La documentation distingue les générations d’API. La même expression « requête idempotente » ne suffit pas à décrire les conditions d’une reprise.

Stripe : distinguer les règles d’idempotence v1 et v2
Point documentéCe que la source préciseConséquence pour votre contrôle
API v1Une fois l’exécution commencée, le premier statut et le corps sont conservés pour la clé, y compris une réponse 500.Relire l’objet et l’état de l’opération avant de changer de clé après une erreur.
Durée de conservation v1Une clé peut être supprimée après au moins 24 heures ; sa réutilisation après suppression peut démarrer une nouvelle requête.Conserver aussi un identifiant métier durable ; la clé HTTP n’est pas une protection permanente.
ParamètresStripe compare les paramètres d’une reprise avec ceux de la première requête.Ne pas réutiliser une clé pour un montant ou un bénéficiaire différent.
API v2La documentation décrit une reprise des requêtes incomplètes ou échouées lorsque c’est possible, avec une réponse pouvant être actualisée.Lire la règle de la version appelée au lieu de transposer automatiquement celle de v1.
Périmètre de reprise /v2Même clé pour la même API, dans le même compte ou sandbox et dans un délai de 30 jours.Noter le namespace, le compte et la date initiale ; une version Stripe ne remplace pas ces informations.

Ces règles concernent Stripe ; elles ne confirment ni la prestation touristique ni le traitement idempotent d’un second système.

Stripe — Idempotent requests · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.

Stripe — périmètre et reprise dans /v2 · consultée le 27/10/2026

Examiner le dossier et son périmètre.

Approfondir ce contrôle

Toutes les fiches de contrôle · Méthode des sources

Approfondir la méthode

Modèles et champs associés

Ces modèles sont reliés à cette fiche ou à ses guides. Choisissez le périmètre qui correspond à votre contrôle. Consultez les informations à rapprocher et les contrôles proposés.

Passer à la vérification

Des fiches de contrôle pour ce sujet

Champs à collecter, tests, erreurs fréquentes et consignes de transmission pour travailler sur un dossier concret.

Vignettes illustratives générées par IA.

Toutes les fiches de contrôle →