http_request_args : fiabiliser les appels sortants d’une extension

Une extension de suivi de colis interroge l’API d’un transporteur à chaque fois qu’un client consulte le statut de sa commande. En local et sur l’hébergement principal de l’agence, tout fonctionne sans accroc. Mais sur un hébergement mutualisé bas de gamme utilisé par l’un des clients de l’agence, environ un appel sur dix échoue avec une erreur de type WP_Error portant le code http_request_failed, sans message plus précis dans les journaux applicatifs habituels.

Après investigation, la cause s’avère être une combinaison de deux facteurs indépendants : un temps de réponse de l’API du transporteur parfois supérieur à la limite par défaut de WordPress, et un user-agent générique qui déclenche occasionnellement une limitation de débit côté fournisseur externe.

Le paramétrage par défaut de l’API HTTP

Toutes les fonctions de la famille wp_remote_get(), wp_remote_post() et wp_remote_request() reposent en interne sur la classe WP_Http, dont les valeurs par défaut incluent un délai d’attente de 5 secondes seulement. Ce délai convient pour l’immense majorité des appels internes ou vers des API rapides, mais devient un facteur d’échec régulier face à une API tierce qui répond parfois en 6 ou 7 secondes sous charge, ce qui est fréquent chez de nombreux fournisseurs de services logistiques ou de paiement.

Ajuster ces paramètres sans répéter le code partout

Plutôt que de passer un tableau d’arguments à chaque appel individuel, ce qui oblige à dupliquer la configuration dans chaque endroit du code qui contacte l’API, le filtre http_request_args permet d’ajuster globalement, ou de façon ciblée selon l’URL de destination, les paramètres de toute requête sortante initiée par WordPress :

add_filter( 'http_request_args', function( $args, $url ) {
    if ( false === strpos( $url, 'api.transporteur-exemple.fr' ) ) {
        return $args; // on ne touche qu'aux appels vers cette API précise
    }

    $args['timeout']     = 15;
    $args['user-agent']  = 'MonExtension/2.3; ' . home_url();
    $args['sslverify']   = true;

    return $args;
}, 10, 2 );

Cibler le filtre sur l’URL de destination, plutôt que de l’appliquer à toutes les requêtes sortantes du site sans distinction, évite de ralentir involontairement d’autres appels HTTP légitimes déclenchés par d’autres extensions ou par le cœur de WordPress lui-même, par exemple les vérifications de mise à jour.

Sur le user-agent

Un user-agent explicite, qui identifie le nom de l’extension, sa version et l’URL du site appelant, sert deux objectifs distincts. D’abord, il facilite le diagnostic côté fournisseur distant si celui-ci doit un jour enquêter sur un pic de trafic suspect associé à son API. Ensuite, certains fournisseurs appliquent des règles de limitation de débit plus souples aux user-agents identifiables qu’aux user-agents génériques ou vides, considérés par défaut comme potentiellement automatisés de façon abusive.

Gérer l’échec malgré tout

Même avec un timeout ajusté, un appel réseau peut échouer, c’est la nature même d’une communication vers un tiers hors du contrôle de l’extension. Le code appelant doit systématiquement vérifier le retour avant de l’utiliser :

$reponse = wp_remote_get( $url_transporteur );

if ( is_wp_error( $reponse ) ) {
    error_log( 'Échec appel transporteur : ' . $reponse->get_error_message() );
    return afficher_statut_indisponible();
}

$code = wp_remote_retrieve_response_code( $reponse );

if ( 200 !== $code ) {
    error_log( sprintf( 'Réponse transporteur inattendue : code %d', $code ) );
    return afficher_statut_indisponible();
}

$corps = json_decode( wp_remote_retrieve_body( $reponse ), true );

Ce garde-fou, combiné à un affichage dégradé mais informatif côté client plutôt qu’une page blanche ou une erreur brute, transforme un échec réseau ponctuel en simple désagrément plutôt qu’en incident visible.

Autres réglages utiles selon le contexte

• redirection : le nombre de redirections HTTP suivies automatiquement, utile à réduire si l’API cible ne redirige jamais et qu’on veut détecter une anomalie de configuration côté fournisseur plus tôt.
• blocking : mis à false pour un appel de type notification qui n’a pas besoin d’attendre la réponse, comme évoqué pour des cas de webhook sortant, mais à manier avec précaution car il empêche alors toute vérification du résultat.
• sslverify : à ne désactiver qu’en tout dernier recours et jamais en production, uniquement pour diagnostiquer un problème de certificat sur un environnement de test isolé.

Un appel réseau qui suppose que le tiers répondra toujours en moins de cinq secondes n’est pas un appel réseau fiable, c’est un pari sur la météo de l’infrastructure d’un autre.

En résumé

Le filtre http_request_args permet d’ajuster finement, sans dupliquer de code, le comportement des appels sortants d’une extension vers une API précise. Combiné à une vérification systématique du résultat côté appelant et à un user-agent identifiable, il réduit sensiblement les échecs intermittents observés sur certains hébergements, sans complexifier l’ensemble du code métier de l’extension.