Ressources · 18

Rendre les intégrations API résilientes aux pannes

Cartographier les dépendances, borner les reprises et maintenir les parcours essentiels lors d’une panne externe.

Mis à jour le 23 octobre 2026 · 10 min

Ce que ce guide permet

Relier API et parcours métier
Limiter les appels et les reprises
Prévoir un mode dégradé
Mesurer le rétablissement

Contrôle express

Quels parcours dépendent de chaque fournisseur ?
Un appel a-t-il un délai explicite ?
Une reprise peut-elle dupliquer une opération ?
Que voit l’utilisateur si le service échoue ?
Qui décide du retour au fonctionnement normal ?

Méthode pas à pas

01
Cartographier les appels
Reliez chaque intégration aux données échangées, contrats, responsables et étapes du parcours métier. Identifiez les appels synchrones qui bloquent l’utilisateur.
Livrable : carte de dépendances priorisée.
02
Fixer les budgets de délai
Définissez un délai par appel et un budget global par parcours. Évitez qu’une chaîne de services multiplie les attentes.
Livrable : matrice des délais et seuils.
03
Encadrer les reprises
Ne répétez que les opérations sûres à rejouer. Testez l’idempotence, limitez le nombre de tentatives et répartissez-les avec un backoff adapté.
Livrable : politique de reprise testée.
04
Préparer la dégradation
Décidez quelles fonctions restent utilisables, quelles données peuvent être mises en attente et quel message honnête afficher en cas d’indisponibilité.
Livrable : comportement de repli par parcours.
05
Simuler les incidents
Introduisez délais, réponses invalides et indisponibilité en environnement contrôlé. Vérifiez charge, données, interface et retour à la normale.
Livrable : résultats de tests de panne.
06
Surveiller les effets
Suivez erreurs, latence, files d’attente et actions métier réellement perdues. Désignez la personne qui escalade et coordonne avec le fournisseur.
Livrable : tableau de bord et procédure de reprise.

Indicateurs de pilotage

Indicateur	Ce qu’il mesure	Première action
Parcours couverts	Parcours essentiels avec dépendances connues	Traiter les appels sans propriétaire
Budget de délai	Appels respectant le délai du parcours	Réviser les attentes en cascade
Reprises sûres	Opérations rejouées sans effet secondaire	Ajouter une clé d’idempotence ou supprimer la reprise
Dégradation vérifiée	Scénarios de panne avec résultat utilisateur testé	Corriger la continuité et la communication

Erreurs fréquentes

Relancer sans limite un service déjà saturé
Rejouer une écriture non idempotente
Masquer une panne par des données périmées non signalées
Mesurer seulement le taux de réponse du fournisseur

Questions fréquentes

Faut-il toujours réessayer ?

Non. Une reprise n’aide que pour certains échecs transitoires et doit respecter le délai global, l’idempotence et la charge du fournisseur.

Un circuit breaker suffit-il ?

Il protège certains appels, mais ne définit ni l’expérience utilisateur ni la reprise des données en attente.

Que mesurer en priorité ?

Les effets sur les parcours essentiels : durée, actions perdues ou retardées et qualité du rétablissement.

Références : données, usages et limites

Documentation consultée le 2026-10-22.

Références : données, usages et limites
Source et objet	Donnée ou repère vérifié	Comment l’utiliser	Limite à conserver
OASIS · TAXII 2.1 Échanger du renseignement sur les menaces par un protocole applicatif.	TAXII 2.1 est un standard OASIS du 10 juin 2021. Il organise notamment la découverte de services et l’accès à des collections.	Testez authentification, droits de collection, pagination et reprise après interruption. Documentez quels objets ont réellement été reçus et traités. Approfondir la méthode →	TAXII transporte des données ; il ne remplace ni leur modèle de contenu ni leur évaluation de fiabilité.

ETag, cache HTTP et modifications concurrentes

Une reprise ne doit pas écraser une version plus récente

Séparer l’échec réseau, le refus de précondition et la décision de réessai. Un 412 n’est pas une invitation à renvoyer la même écriture en boucle.

Conserver l’ETag associé à la représentation qui a servi à préparer PUT.
Après 412, relire et résoudre le conflit ; un backoff seul ne réconcilie pas les changements.
Documenter à part les doublons et les requêtes dont le résultat est inconnu : ils sont hors du simulateur de préconditions.

Explorer les comparaisons et le simulateur ETag →

Références relues le 2026-10-22 · RFC 9110 · §13 · RFC 9111 · RFC 6585 · §3

Idempotence et contrats de reprise API

Comparer une propriété HTTP et un contrat de fournisseur

L’idempotence HTTP porte sur l’effet demandé de requêtes identiques. Une clé de reprise applicative relève du contrat de l’API concernée. Les détails Stripe ci-dessous sont attribués à sa documentation consultée le 22 octobre 2026 ; ils ne décrivent pas toutes les API et ne sont pas simulés par le modèle de budget.

Réponse perdue : trois vérifications avant une nouvelle écriture

Après une réponse perdue, relier l’opération à l’état métier vérifié. Vérifier ensuite la même identité d’opération, le contrat de reprise et son contexte. Choisir enfin un rapprochement ou une reprise bornée ; changer arbitrairement la clé ne prouve pas l’absence d’un premier effet.

Six différences ou limites à documenter chez Stripe

Six différences ou limites à documenter chez Stripe
Point comparé	API v1	API v2
Méthodes avec clé	Les POST acceptent la clé. En envoyer sur GET ou DELETE n’a pas d’effet dans ce contrat.	Les POST et DELETE acceptent les clés ; GET est idempotent par définition et la clé n’a pas d’effet.
Résultat réutilisé	Après début d’exécution, le statut et le corps initiaux sont enregistrés ; une reprise peut rendre la même erreur 500.	Une réussite n’est pas répétée. Un échec ou échec partiel peut être repris pour obtenir une réponse actualisée ; une reprise devenue impossible rend une erreur explicative.
Fenêtre et conservation	La page dédiée permet la suppression d’une clé après au moins 24 heures. Une clé réutilisée après suppression crée une nouvelle requête.	Le rejeu documenté se situe dans les 30 jours, pour la même API et dans le même compte ou sandbox.
Paramètres et périmètre	La couche compare les paramètres aux paramètres initiaux et refuse une réutilisation incompatible.	Le contexte de même API et de même compte ou sandbox fait partie des conditions de rejeu ; relire le contrat exact de l’endpoint.
Avant l’exécution	Une validation en échec ou un conflit concurrent qui n’initie pas l’endpoint ne produit pas de résultat idempotent enregistré, selon la page v1.	Ne pas recopier une exception v1 sans vérifier la documentation v2 et le comportement de l’endpoint utilisé.
Identifiant durable	Une clé doit rester liée à la même intention et aux paramètres retenus ; la doc conseille de ne pas y mettre de données sensibles.	Une génération automatique de clé côté service ne dispense pas le client de rattacher correctement ses reprises à l’opération.

Le statut ne dit pas tout : Stripe-Should-Retry

Le statut ne dit pas tout : Stripe-Should-Retry
Valeur documentée	Indication Stripe	Limite
true	Réessayer avec un backoff exponentiel selon la documentation d’erreurs.	Vérifier aussi identité de l’opération, contexte, budget et contrat.
false	Ne pas réessayer cette requête.	Ne pas remplacer cette indication par un test générique « tout 5xx est rejouable ».
Absent	Décider avec le statut et les autres informations de réponse.	L’absence n’est ni une garantie d’échec sans effet ni une obligation de reprise.

Quatre reprises qui demandent une preuve différente

Réponse perdue après envoi

Un client ne reçoit pas la réponse à une création.

Retrouver l’opération et son état dans la source autorisée ; conserver la même clé si le contrat permet la reprise de cette même intention.

Une nouvelle clé peut décrire une nouvelle opération et produire un second effet.

Même clé, paramètres modifiés

Le client change le contenu tout en réutilisant une clé.

Comparer les paramètres au contrat et séparer correction de la demande et répétition identique.

Dans le contrat v1 décrit, des paramètres incompatibles déclenchent une erreur ; ne pas contourner en changeant de clé sans décision métier.

Clé disparue de la fenêtre de reprise

L’application veut rejouer une demande longtemps après.

Relire la durée, l’API, le compte et l’état métier ; ne pas supposer que le fournisseur conserve indéfiniment le premier résultat.

Une clé historique n’est pas une preuve d’unicité permanente.

Deux workers pour le même effet

Deux traitements lisent simultanément « effet absent ».

Tester la revendication atomique de l’effet local et le contrat de l’effet externe ; conserver la trace des deux réceptions.

Un SELECT préalable ou une contrainte locale seule ne garantit pas l’unicité d’un effet chez un fournisseur distant.

Trois identités à garder distinctes

Trois identités à garder distinctes
Identité	Rôle dans un exemple de webhook	Limite
Clé de requête	Reconnaître la reprise d’une même requête cliente selon le contrat de l’API.	Ne constitue pas automatiquement l’identifiant d’un événement reçu.
Identifiant d’événement	Relier les répétitions d’une notification d’un fournisseur et de son contexte.	Deux événements distincts peuvent concerner le même effet métier.
Clé d’effet métier	Empêcher une répétition locale de l’action métier choisie, avec un mécanisme atomique adapté.	L’effet distant exige sa propre garantie, une reprise maîtrisée et un rapprochement.

Explorer Retry-After et le modèle de reprise →

Sources primaires et limites

Les RFC définissent les éléments HTTP cités. AWS décrit des choix de conception ; Stripe documente ses propres API. Les budgets, attentes locales, cas et schéma sont pédagogiques, sans mesure de votre service ni exécution d’une requête.

IETF · RFC 9110 — Retry-After et idempotence HTTP · June 2022 · STD 97
§5.6.7; §9.2.2; §10.2.3; §15.6.4
IETF · RFC 6585 — 429 Too Many Requests · April 2012 · Standards Track
§4
AWS Builders’ Library · Timeouts, retries, and backoff with jitter · Published 2019-12-05; accessed 2026-10-22
Retries; jitter; timeout scope
Stripe · Idempotent requests · Documentation accessed 2026-10-22
API v1: saved results, parameters, key pruning, execution boundary
Stripe · API v2 overview — Idempotency · Documentation accessed 2026-10-22
POST/DELETE; same API and account/sandbox; 30-day replay window
Stripe · Advanced error handling · Documentation accessed 2026-10-22
Stripe-Should-Retry; status codes; idempotency

Références relues le 2026-10-22

OAuth/OIDC : audience et droits

Renouveler un jeton ne dispense pas de gérer la fin des accès

Séparez le cycle de vie des sessions, des access tokens et des refresh tokens dans la procédure d’exploitation. Une déconnexion locale ne démontre pas leur invalidation simultanée.

Mesurer le délai résiduel avec des comptes et objets de test autorisés.
Exercer expiration, révocation et panne fournisseur sans journaliser les secrets.
Documenter les réponses attendues et le responsable de reprise de l’intégration.

Voir les destinataires et les dix scénarios OAuth/OIDC →

Sources vérifiées le 2026-10-22 · IETF · RFC 9700 · OAuth 2.0 Security BCP · IETF · RFC 9068 · JWT access token profile · OpenID Foundation · OpenID Connect Core 1.0 · IETF · RFC 8725 · JWT Best Current Practices · IETF · RFC 6749 · OAuth 2.0 framework

Webhooks : signatures et rejeu

Une reprise API et une reprise webhook suivent deux contrats

Pour une notification entrante, suivez l’événement, la tentative de transport et l’effet métier séparément. La signature authentifie un message ; elle ne constitue pas une clé d’idempotence.

Conserver les octets bruts requis et authentifier chaque nouvelle tentative.
Préparer une reprise propre au fournisseur : Stripe peut réessayer automatiquement ; GitHub ne relivre pas automatiquement les échecs.
Tester réponse perdue, concurrence et rapprochement après panne.

Voir les signatures, les empreintes et les dix cas webhooks →

Sources vérifiées le 2026-10-22 · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries

SSRF : URL et connexions

Un retry ne change pas la politique de destination

La résilience d’un import par URL doit préserver les contrôles de sortie. Une adresse de repli, un proxy ou une redirection constitue une nouvelle étape à vérifier, même si la première chaîne a passé le contrat applicatif.

Utiliser le même parseur et les mêmes champs entre validation et client HTTP.
Relier les adresses validées aux connexions effectives en conservant TLS et le nom original.
Tester les refus et les limites dans un laboratoire autorisé, sans sonder des services tiers.

Lire les 12 cas et les contrôles de connexion →

Sources relues le 2026-10-22 · OWASP · SSRF Prevention Cheat Sheet · WHATWG · URL Living Standard · AWS EC2 · Instance metadata options · IETF · RFC 3849

Pagination : cohérence et reprise

Le point de reprise suit le lot effectivement conservé

Une relance doit savoir quels objets ont été conservés et dans quelle vue. Avancer la continuation avant la confirmation du lot peut perdre des données ; relire le lot demande une déduplication et une politique d’effets externes.

Tester une panne entre conservation du lot et point de contrôle.
Ne pas annoncer la fin sur la seule taille de page.
Revérifier les permissions et la validité de la référence à chaque reprise.

Comparer les lectures et les reprises calculées →

Sources relues le 2026-10-22 · Google · AIP-158 Pagination · PostgreSQL 18 · LIMIT and OFFSET · PostgreSQL 18 · Row constructor comparison · PostgreSQL 18 · Transaction isolation · OWASP · API1:2023 Broken Object Level Authorization

Erreurs API : types, statuts et preuves

Traiter une erreur sans analyser sa phrase

Un client API peut recevoir un titre traduit, un membre manquant ou une extension qu’il ne connaît pas. Préservez une décision fondée sur le type documenté et le statut HTTP, puis associez une action sûre au contexte.

Comparer statut reçu et status du JSON sans remplacer silencieusement l’un par l’autre.
Tester un type absent, une chaîne à la place du nombre status et une extension inconnue.
Séparer message destiné à la personne, code métier et référence d’occurrence.

Explorer les types de problèmes et les huit réponses fictives →

IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5

API : dépréciation et retrait

Une intégration peut rester disponible tout en étant déjà dépréciée. Préparer sa migration demande donc de séparer le cycle de vie annoncé, l’état réel du service et les dépendances qui restent à déplacer. Ce dossier ajoute les signaux HTTP utiles, une lecture des échéances et des contrôles de sortie pour les équipes API, exploitation et sécurité.

Repères : RFC 9745 (mars 2025) pour Deprecation et RFC 8594 (mai 2019, document informatif) pour Sunset. Lorsque les deux dates sont fournies, Sunset ne doit pas être antérieur à Deprecation. Leur égalité respecte cette relation temporelle ; elle ne démontre pas qu’un préavis suffisant a été accordé.

IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23

IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23

Quatre signaux pour préparer une migration

Quatre signaux pour préparer une migration
Signal	Ce qu’il communique	Format ou nature	Limite à conserver
`Deprecation`	Annonce une dépréciation passée ou future de la ressource concernée.	Date Structured Fields, pas date HTTP textuelle.	Ne change pas à elle seule le comportement de la ressource.
`Sunset`	Indique quand la ressource est susceptible de ne plus répondre.	HTTP-date ; format émis IMF-fixdate avec GMT.	Indice de retrait, sans garantie de disponibilité avant ou après.
`Link · rel="deprecation"`	Renvoie vers une documentation de dépréciation.	Relation de lien ; ce n’est pas une date.	La documentation peut être exposée avant une annonce datée.
`Link · rel="sunset"`	Renvoie vers des informations ou une politique de retrait.	Relation de lien ; ce n’est pas une échéance.	Consulter le périmètre et les conditions effectivement documentés.

Deux formats de date à ne pas intervertir

Deux formats de date à ne pas intervertir
Exemple pédagogique	Lecture	Référence
Deprecation: @1688169599	30 juin 2023 à 23:59:59 UTC. Le nombre représente des secondes depuis l’époque Unix, avec le préfixe @.	RFC 9745 §2.1 ; RFC 9651 §3.3.7
Sunset: Sun, 30 Jun 2024 23:59:59 GMT	Exemple CIE au format IMF-fixdate : jour anglais, date et GMT. Ne pas recopier une date ISO à cet emplacement.	RFC 8594 §3 ; RFC 9110 §5.6.7

IETF · RFC 9651 · Structured Fields · Standards Track · September 2024 · §3.3.7 · consulted 2026-10-23

IETF · RFC 9110 · HTTP semantics · Internet Standard · June 2022 · §5.6.7 · consulted 2026-10-23

Lire une chronologie UTC

Comparer des instants déjà normalisés en UTC. Le lecteur ne décode pas les en-têtes HTTP : il travaille sur les dates extraites et vérifiées par vos soins. Les deux échéances sont facultatives ; l’instant de lecture est obligatoire. Les exemples utilisent un instant fixe afin que les résultats restent reproductibles.

Profil de saisie CIE : YYYY-MM-DDTHH:mm:ssZ, années 1970 à 2099, secondes de 00 à 59, sans fractions, espaces ni décalage numérique. Ces limites servent à rendre l’atelier prévisible ; elles ne décrivent pas toute la syntaxe des RFC. Une date vide signifie « non renseignée dans cet exercice », pas « cette politique n’existe pas ».

Calcul local, sans requête réseau, import, stockage ou export. Le lecteur n’atteste ni disponibilité, ni compatibilité, ni conformité complète des en-têtes. Il ne déduit aucun délai minimal de migration : vérifier contrat, politique, dépendances et interlocuteur du fournisseur. Le franchissement d’une date Sunset reste un indice annoncé, pas la preuve d’un arrêt réel.

Les écarts d’échéance à l’instant de lecture sont signés : négatif signifie passé, zéro signifie atteint, positif signifie à venir. L’intervalle Sunset − Deprecation compare les deux annonces ; une valeur négative signale leur ordre incohérent. Les valeurs sont exprimées en secondes exactes dans le profil, sans convertir en jours calendaires locaux.

Neuf scénarios de lecture, disponibles sans JavaScript

V01 · Dépréciation à venir

Dépréciation à venir
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-11-01T00:00:00Z	2026-12-01T00:00:00Z	2026-10-23T00:00:00Z	Deux échéances futures, séparées de 2 592 000 secondes. Ce calendrier n’atteste pas que le préavis convient au contrat.

V02 · Dépréciation déjà effective

Dépréciation déjà effective
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-10-01T00:00:00Z	2026-12-01T00:00:00Z	2026-10-23T00:00:00Z	Deprecation est passée, Sunset est futur. Cela ne signifie pas que la ressource a déjà cessé de fonctionner.

V03 · Date Sunset atteinte

Date Sunset atteinte
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-10-01T00:00:00Z	2026-10-23T00:00:00Z	2026-10-23T00:00:00Z	L’écart Sunset − lecture vaut zéro. Vérifier l’état réel du service et la migration ; le champ reste un indice.

V04 · Ordre contradictoire

Ordre contradictoire
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-11-01T00:00:00Z	2026-10-01T00:00:00Z	2026-10-23T00:00:00Z	Sunset précède Deprecation de 2 678 400 secondes. Demander clarification plutôt que supposer un calendrier cohérent.

V05 · Sunset seul

Sunset seul
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
—	2026-12-01T00:00:00Z	2026-10-23T00:00:00Z	Une date de retrait est fournie, mais aucune date Deprecation n’est renseignée dans l’exercice. Ne pas inventer la date manquante.

V06 · Deprecation seule

Deprecation seule
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-10-01T00:00:00Z	—	2026-10-23T00:00:00Z	La dépréciation est effective à l’instant choisi ; aucune date de retrait n’est fournie. Ne pas en déduire une durée de support.

V07 · Aucune échéance renseignée

Aucune échéance renseignée
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
—	—	2026-10-23T00:00:00Z	L’absence de dates dans cette saisie ne garantit ni pérennité ni absence de politique externe.

V08 · Date calendaire impossible

Date calendaire impossible
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-02-29T00:00:00Z	2026-12-01T00:00:00Z	2026-10-23T00:00:00Z	2026 n’est pas bissextile. La saisie est refusée au lieu d’être normalisée silencieusement en mars.

V09 · Deux dates égales à la lecture

Deux dates égales à la lecture
Deprecation normalisée	Sunset normalisé	Instant de lecture UTC	Lecture attendue
2026-10-23T00:00:00Z	2026-10-23T00:00:00Z	2026-10-23T00:00:00Z	L’ordre des dates respecte la relation non antérieure, avec un intervalle nul. Cela ne prouve pas qu’une période de migration a été proposée.

Constituer les preuves d’une sortie maîtrisée

Constituer les preuves d’une sortie maîtrisée
Contrôle proposé	Élément vérifiable
Périmètre	Ressource, opérations, version, environnement et politique concernés ; ne pas généraliser une réponse à toutes les routes.
Consommateurs	Responsables, SDK, traitements planifiés et intégrations partenaires ; rapprocher inventaire déclaré et usage observé.
Calendrier	Origine de l’annonce, dates UTC, mises à jour et interlocuteur habilité à confirmer un changement.
Remplacement	Tests des anciens parcours sur la cible : données, droits, erreurs, pagination et effets de bord.
Coexistence	Critère de bascule, stratégie de retour et traitement des opérations en cours ou rejouées.
Clôture	Vérification des consommateurs restants, retrait des secrets devenus inutiles, mise à jour de la documentation et contrôle du résultat métier.

Une alerte utile relie une échéance à un consommateur et à une action vérifiable. Noter ce qui est annoncé, ce qui a été effectivement testé et ce qui reste inconnu. Si deux dates se contredisent, demander clarification au fournisseur avant de transformer cette chronologie en calendrier de bascule.

Sources, éditions et crédits

Synthèses originales CIE d’après les RFC 9745, 8594, 9651 et 9110. Scénarios et contrôles pédagogiques fictifs. Le programme de comparaison est original ; aucun algorithme de RFC n’est reproduit. Le second exemple de date est rédigé par CIE avec GMT, selon le format d’émission défini par HTTP.