Diagnostiquer un incident API sans créer de doublon

Un incident API peut laisser une opération refusée, en attente ou déjà exécutée sans réponse exploitable. Le diagnostic consiste à retrouver l’objet, la dernière étape confirmée et ce qui existe dans le logiciel destinataire avant de choisir une action.

Relancer une création après une interruption peut produire un doublon. Corriger une donnée ne résout pas un problème de quota. Le statut HTTP, les traces et l’état métier doivent donc être lus ensemble, en conservant les informations nécessaires pour comprendre les effets de la demande initiale.

La matrice ci-dessous distingue les problèmes d’accès, les données refusées, la saturation et le résultat incertain. Elle indique la preuve à chercher, l’action envisageable et ce qui doit bloquer une reprise. Les scénarios et identifiants utilisés sont fictifs ; ils servent à tester le raisonnement, pas à reproduire une API client.

Le guide d’intégration API explique la chaîne source–destination et ses contrôles. Retrouver l’étape bloquée et les effets déjà produits permet ensuite de préparer une reprise vérifiable. Pour cadrer la reprise d’un échange existant avec vos équipes, notre accompagnement en intégration API permet de préciser le périmètre, les accès et les critères de validation.

1. Choisir la prochaine vérification avant de reprendre

Commencez par un objet et une opération. La réponse HTTP oriente le diagnostic, mais sa signification détaillée reste celle du fournisseur. La matrice ne constitue pas une autorisation automatique de relancer : les effets déjà produits et les garanties disponibles doivent être vérifiés.

Les délais d’attente, les volumes de lot et les seuils d’escalade sont des paramètres du parcours. Ils dépendent des garanties du fournisseur, de la capacité disponible et des conséquences métier. Une seule opération sensible peut exiger une validation spécifique ; le volume de messages ne prouve pas à lui seul qu’une reprise est sûre.

2. Identifier l’objet, l’opération et son impact

Une alerte doit conduire à une référence que les équipes peuvent retrouver. Relevez l’objet métier, le système source, la destination, l’opération demandée et le dernier résultat confirmé. Distinguez une création, une mise à jour, une lecture et un retour d’information : leurs effets ne sont pas identiques.

Pour une commande, précisez si l’incident concerne sa transmission, sa préparation, son expédition ou une écriture ERP. Pour une facture, séparez l’objet comptable du document publié dans un portail. Une pièce invisible pour un utilisateur ne prouve pas que la facture n’existe pas dans le système de référence.

Délimiter le périmètre avant l’action

Identifiez les objets voisins potentiellement affectés et les traitements qui peuvent encore agir sur eux. Un batch de rattrapage, une notification et une reprise manuelle peuvent toucher la même commande. Le périmètre doit donc porter sur les opérations et leurs effets, pas uniquement sur le nombre de messages visibles dans une file.

Nommez la personne autorisée à décider et celle qui vérifie le résultat métier. Le guide de pilotage d’un incident sur un flux critique approfondit l’activation, les responsabilités et la communication. Le diagnostic technique présenté ici lui fournit des faits exploitables.

3. Distinguer transport, réponse HTTP et rejet métier

Une erreur de transport peut empêcher de recevoir une réponse complète. Une réponse HTTP décrit le traitement de la requête selon le protocole. Le résultat métier demande encore de vérifier l’objet concerné. Gardez ces trois niveaux séparés dans les traces et dans le ticket.

Un timeout après envoi n’indique pas nécessairement que le destinataire n’a rien fait. Une réponse 202 peut correspondre à une demande acceptée pour traitement ultérieur. Un résultat 200 ne garantit pas que toutes les étapes d’un parcours multi-systèmes sont terminées. La documentation doit indiquer où lire l’état final attendu.

Lire le code avec le contrat de l’interface

Un 409 peut signaler un conflit avec l’état de la ressource ; un 422 peut concerner une demande que le service ne peut pas traiter telle quelle. Les détails du fournisseur précisent la règle et les possibilités de correction. Une même action de reprise ne peut pas être déduite de ces codes pour tous les logiciels.

Conservez le code d’erreur applicatif et les champs utiles lorsqu’ils sont fournis, après filtrage des informations sensibles. Pour une donnée refusée, le guide de mapping des champs API aide à retrouver la correspondance, la transformation et le test à corriger.

4. Rassembler des preuves comparables

Le relevé minimal associe l’heure, l’opération, la référence source, la destination, un identifiant de corrélation disponible et le résultat observé. Ajoutez la version de transformation ou le numéro de lot lorsqu’ils sont réellement conservés par votre dispositif. Ces propriétés ne sont pas présentes dans toutes les API.

Comparez les traces sur la même opération et dans le même environnement. Une erreur de préproduction, une lecture ancienne et une tentative récente ne forment pas une chronologie fiable simplement parce qu’elles partagent un numéro de commande. Notez la provenance de chaque preuve et ce qu’elle confirme précisément.

Conserver les informations utiles sans recopier les secrets

Le ticket peut référencer un appel et une version d’accès sans contenir le jeton, le header Authorization ou un corps complet avec des données personnelles. Utilisez les outils et les espaces protégés prévus pour l’incident, avec les personnes habilitées et la durée de conservation adaptée.

Les conventions HTTP OpenTelemetry fournissent un vocabulaire pour rapprocher les signaux techniques. Les identifiants métier ajoutés aux traces demandent aussi une maîtrise de la confidentialité et de la cardinalité. Une collecte plus abondante ne garantit pas un meilleur diagnostic.

5. Vérifier l’accès et les limites de débit

Pour un accès refusé, contrôlez le logiciel et l’environnement appelés, l’identité de l’application, l’expiration et les permissions attendues. Examinez les changements récents : remplacement d’un secret, modification de droits ou nouvelle configuration. Un refus d’accès ne constitue pas à lui seul une preuve de compromission.

Le guide sur les accès et secrets d’une intégration API distingue renouvellement, rotation planifiée et incident de sécurité. Ne rétablissez pas un accès en élargissant automatiquement ses permissions ou en désactivant un contrôle de certificat.

Ralentir sans perdre l’opération

En cas de limitation de débit, examinez les consommateurs qui partagent le quota, les reprises déjà planifiées et les indications du fournisseur. Respectez le mécanisme de temporisation disponible, notamment Retry-After lorsqu’il est fourni, avec une politique de reprise bornée adaptée à l’opération.

Le nombre de tentatives doit rester visible. Une reprise automatique ne doit pas ajouter une charge incontrôlée à un service déjà saturé. Le guide des retries, du backoff et du circuit breaker approfondit ces mécanismes ; leur paramétrage dépend du contrat et des effets du parcours.

6. Reconstituer la chronologie des traitements

Pour un échange asynchrone, distinguez notification reçue, message enregistré, prise en charge, appel destinataire et résultat métier confirmé. Une file vide ne prouve pas que tous les objets existent à destination. Un webhook reçu ne prouve pas que son traitement a abouti.

Relevez les étapes effectivement observables dans votre architecture. Un connecteur natif peut fournir un journal d’exécution ; une plateforme d’intégration peut exposer ses traitements ; un middleware peut conserver une référence d’opération et une mise en attente. Ne demandez pas au support une information que le dispositif ne collecte pas.

Examiner les traitements concurrents

Une correction manuelle peut être suivie par un événement plus ancien ou par un batch préparé avant cette correction. Utilisez les versions ou séquences disponibles et l’autorité de la donnée pour interpréter l’ordre. L’heure d’arrivée seule ne démontre pas toujours quel état doit être conservé.

Avant de modifier une file, vérifiez les traitements en cours et les possibilités réelles d’arrêt ou d’isolement. L’objectif est de contenir les effets indésirables sans perdre la référence des opérations à examiner. Toute action doit conserver un périmètre, un responsable et un contrôle de résultat.

7. Établir les effets déjà produits à destination

La recherche doit utiliser les références prévues : identifiant distant, référence externe, clé de corrélation ou autre mécanisme officiellement disponible. Un nom approchant ou une recherche partielle ne suffisent pas forcément à établir qu’un objet existe ou n’existe pas.

Pour une API à traitement différé, une réponse de lecture temporairement vide peut précéder la création finale. Examinez les garanties de cohérence, les états d’exécution et les fenêtres documentées. Si le résultat reste incertain, conservez ce statut plutôt que le transformer en « échec sans effet ».

Distinguer une étape terminée d’un parcours complet

Une commande logistique peut être créée alors que son retour vers l’ERP a échoué. Le diagnostic doit distinguer ces étapes pour éviter de recréer la commande en réparant seulement le retour. Vérifiez les lignes, quantités et états utiles, pas uniquement la présence d’un identifiant.

Une preuve d’effet partiel change la décision. Il peut être nécessaire de corriger ou de reprendre une étape précise, selon les garanties et les procédures autorisées. Elle ne justifie pas de rejouer toute la chaîne avec une nouvelle référence en espérant obtenir un résultat plus clair.

8. Conditionner la reprise à des garanties explicites

Pour une écriture non idempotente, ne déclenchez pas une répétition automatique sans moyen de connaître ses garanties d’idempotence ou d’établir que la demande initiale n’a pas été appliquée. La RFC 9110 sur les méthodes idempotentes pose cette distinction. Une clé ajoutée localement ne contraint pas un fournisseur à dédupliquer une création.

La décision doit préciser l’opération relancée, les références conservées, la politique de temporisation, les limites et la preuve attendue après l’action. Le guide sur l’idempotence et les doublons métier approfondit les conséquences des répétitions.

Trois gestes à refuser sans vérification

• Recréer après un timeout. Un silence de la connexion ne prouve pas l’absence d’effet dans le logiciel destinataire.
• Relancer un lot complet pour une étape manquante. Distinguez les opérations déjà confirmées de celles qui restent à traiter.
• Modifier les données pour contourner un refus. La règle métier, la personne qui peut la corriger et les conséquences doivent être identifiées.

Une attente bornée reste une décision si elle possède une raison, une heure de vérification et un responsable. Un isolement doit préciser ce qui reste actif et comment reprendre les opérations conservées. Ces décisions doivent être compréhensibles avant leur exécution, y compris lorsque le métier demande une remise en service rapide.

9. Collecter une preuve HTTP sans déclencher de rejeu

La première sonde doit observer une opération de lecture documentée. L’URL api.example.test est fictive. Le fichier de configuration curl privé mentionné dans cet exemple est préparé par votre dispositif de gestion d’accès ; il n’est ni publié ni recopié dans le ticket.

curl --config "$API_READ_CURL_CONFIG" \
  --silent --show-error --max-time 8 \
  --request GET "https://api.example.test/v1/orders/EXEMPLE-42" \
  --header "X-Correlation-Id: diagnostic-exemple-42" \
  --output /dev/null \
  --write-out 'status=%{http_code} duration=%{time_total}\n'

Cette commande collecte le statut et la durée sans enregistrer le corps. Les valeurs de délai sont pédagogiques et doivent être adaptées au parcours. Conservez aussi le résultat de transport fourni par curl : une connexion interrompue et une réponse HTTP d’erreur ne sont pas le même constat.

Préserver le diagnostic lorsque le corps n’est pas du JSON

Un fournisseur peut répondre en HTML pendant une panne. Dans Symfony, toArray(false) peut encore lever une exception de décodage ; le paramètre désactive le rejet lié au statut HTTP, pas toutes les erreurs. La documentation du client HTTP Symfony distingue les exceptions HTTP, de transport et de décodage.

La sonde suivante conserve le statut lorsqu’il est disponible, distingue un corps vide, JSON, JSON invalide ou d’un autre format, et ne retourne ni le jeton ni le corps métier. Elle ne relance aucune requête. L’adresse de lecture doit provenir de la configuration autorisée du connecteur ; cet exemple n’est pas un service acceptant des URL arbitraires.

<?php

use Symfony\Contracts\HttpClient\HttpClientInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;

function inspectApiRead(
    HttpClientInterface $client,
    string $readUrl,
    string $readToken,
    string $correlationId,
): array {
    $status = null;

    try {
        $response = $client->request('GET', $readUrl, [
            'auth_bearer' => $readToken,
            'headers' => ['X-Correlation-Id' => $correlationId],
            'timeout' => 3.0,
            'max_duration' => 8.0,
            'max_redirects' => 0,
        ]);
        $status = $response->getStatusCode();
        $headers = $response->getHeaders(false);
        $content = $response->getContent(false);
        $contentType = $headers['content-type'][0] ?? '';
        $bodyState = $content === '' ? 'empty' : 'not_json';

        if ($content !== '' && str_contains(strtolower($contentType), 'json')) {
            try {
                json_decode($content, true, 512, JSON_THROW_ON_ERROR);
                $bodyState = 'json_valid';
            } catch (\JsonException) {
                $bodyState = 'json_invalid';
            }
        }

        return [
            'status' => $status,
            'content_type' => $contentType,
            'retry_after' => $headers['retry-after'][0] ?? null,
            'body_state' => $bodyState,
            'correlation_id' => $correlationId,
        ];
    } catch (TransportExceptionInterface) {
        return [
            'status' => $status,
            'transport_error' => true,
            'correlation_id' => $correlationId,
        ];
    }
}

Les délais de cet exemple sont des paramètres de démonstration. En exploitation, les limites de durée et de taille de réponse doivent être définies pour l’interface. Un contenu JSON syntaxiquement valide ne prouve pas que son schéma ou son résultat métier sont corrects.

La recette de la sonde doit couvrir un JSON normal, un corps vide, un accès refusé, une limitation de débit, une réponse HTML et une interruption de transport. La lecture du statut doit rester possible lorsqu’un corps ne correspond pas au format attendu, et aucune donnée secrète ne doit apparaître dans le diagnostic retourné.

10. Tester trois diagnostics complets

Les scénarios suivants sont fictifs. Ils servent à vérifier si le document permet de prendre une décision cohérente avec les preuves, sans attribuer un incident ou un résultat mesuré à un client.

Une commande refusée pour référence inconnue

La réponse documente une référence produit absente du référentiel destinataire. Retrouver la commande source et la correspondance permet de qualifier le défaut. Le responsable de la donnée corrige la référence ou la table validée, puis l’équipe vérifie les conditions d’une nouvelle transmission. Répéter le message identique ne corrige pas la cause.

Une création interrompue dont le résultat est incertain

La connexion se coupe après l’envoi, sans confirmation exploitable. Le diagnostic recherche l’objet par le mécanisme prévu et examine l’exécution différée éventuelle. Sans preuve fiable ni garantie d’idempotence pour cette opération, aucune répétition automatique n’est autorisée par ce seul constat. La décision et la vérification suivante restent explicites.

Un retour d’expédition sans confirmation ERP

La logistique confirme l’expédition et sa référence, mais l’étape de gestion n’est pas confirmée dans l’ERP. Le relevé doit cibler l’écriture ERP et ses prérequis. Recréer l’expédition ferait porter la correction sur une étape déjà réalisée. La clôture exige de retrouver le résultat attendu dans l’ERP, avec les bonnes références et quantités.

11. Réconcilier les résultats et préparer la clôture

Après une action, vérifiez les références, les quantités et les états dans les systèmes concernés. Une file qui se vide ou une alerte qui disparaît ne suffisent pas à prouver la correction. Le résultat métier doit être comparé à ce qui était attendu avant l’action.

Conservez l’état observé avant et après, la décision, la personne qui l’a validée et les opérations restant en attente. Le guide de réconciliation entre source et destination approfondit l’examen des écarts. Les données nécessaires à cette preuve restent filtrées et protégées.

Exercer le diagnostic avant le prochain incident

Faites lire un scénario à une personne du support et à un responsable technique avec les mêmes preuves disponibles. Comparez la prochaine vérification, l’action interdite et la condition de clôture. Une divergence révèle une règle manquante ou une information inaccessible ; elle fournit une correction concrète du document.

Mesurez ce qui aide la décision : opérations qualifiées, causes récurrentes, reprises non concluantes et écarts après correction, selon votre contexte. Le calendrier de préparation et les seuils dépendent du parcours, des garanties disponibles et des exercices à organiser.

12. Lire une chaîne réelle sans lui attribuer les incidents fictifs

Le projet 1UP Distribution entre Wix, ShippingBo et Odoo documente des échanges autour de la commande, de l’expédition et des objets de gestion, avec journaux et reprises. Il illustre pourquoi le diagnostic doit localiser une étape et conserver ses références.

Le retour vers le canal de vente et les sorties vers l’ERP ont des contrats distincts. La fiche fournit un contexte de réalisation ; les trois scénarios de ce guide restent des exercices pédagogiques, sans affirmation de panne rencontrée ni de gain de temps mesuré chez 1UP.

13. Compléter le diagnostic au bon endroit

Le pilotage d’un incident sur un flux critique traite les responsabilités et la communication. L’observabilité API et ses runbooks approfondit l’instrumentation et les alertes. Ces sujets restent distincts du diagnostic d’une opération.

Pour une cause particulière, utilisez le mapping des champs, les accès et secrets ou les garanties d’idempotence. Le guide d’intégration API replace ces contrôles dans le parcours complet.

14. Conclusion : établir les effets avant de choisir la reprise

Le diagnostic commence par une opération identifiable et une dernière étape confirmée. Le statut HTTP, les traces et l’objet métier fournissent des preuves complémentaires.

Avant une écriture répétée, examinez les effets de la demande initiale et les garanties d’idempotence. Si l’état reste incertain, conservez cette incertitude et préparez une décision explicite plutôt qu’un rejeu aveugle.

La clôture demande le résultat attendu à destination et l’explication des écarts restants. Les essais fictifs et les références conservées permettent de vérifier le document avant qu’il ne soit utilisé sous pression.

Pour organiser ce diagnostic et les reprises de vos échanges réels, notre accompagnement en intégration API permet de cadrer les accès, les preuves utiles, la recette et la maintenance avec les interlocuteurs concernés.