« The Retry-After header can be used with a 503 (Service Unavailable) response to indicate how long the service is expected to be unavailable » — cette précision, tirée de la spécification HTTP elle-même, décrit exactement un cas fréquent dans une extension WordPress qui protège une route REST personnalisée derrière une API tierce elle-même saturée ou temporairement indisponible.
Quand une route REST personnalisée dépend d’un appel à une API externe — un service de paiement, un fournisseur d’envoi d’emails, un annuaire professionnel —, cette API peut se retrouver temporairement saturée ou en maintenance. La réponse la plus courante, mais la moins informative, consiste à renvoyer une erreur générique 500. Un code 503, accompagné d’un en-tête Retry-After, transmet une information bien plus exploitable au client de l’API : ce n’est pas cassé, c’est temporairement indisponible, et voici une estimation du délai avant de réessayer.
Distinguer 500 et 503 dans une route personnalisée
Le code 500 signale une erreur interne inattendue, souvent un bug à corriger côté serveur. Le code 503 signale une indisponibilité temporaire du service, généralement transitoire et hors du contrôle direct du code appelé. Confondre les deux prive le client de l’API d’une information essentielle : faut-il signaler un incident au développeur, ou simplement réessayer un peu plus tard ?
Implémentation dans une route WP REST
function mon_extension_callback_route( WP_REST_Request $requete ) {
$reponse_api = wp_remote_get( 'https://api-tierce.exemple.com/statut' );
if ( is_wp_error( $reponse_api ) ||
wp_remote_retrieve_response_code( $reponse_api ) >= 500 ) {
$reponse = new WP_REST_Response(
array(
'code' => 'service_indisponible',
'message' => 'Le service tiers est momentanément indisponible. Réessayez dans quelques instants.',
),
503
);
$reponse->header( 'Retry-After', '120' );
return $reponse;
}
// Traitement normal si l'API tierce répond correctement
return new WP_REST_Response( array( 'statut' => 'ok' ), 200 );
}La valeur transmise dans Retry-After peut être un nombre de secondes, comme ici, ou une date HTTP complète si le délai exact est connu à l’avance (par exemple, une fenêtre de maintenance planifiée communiquée par le fournisseur de l’API tierce).
Calculer un délai réaliste plutôt qu’une valeur arbitraire
Une valeur fixe de 120 secondes reste acceptable en première approche, mais un délai plus réaliste peut être calculé si l’API tierce fournit elle-même un en-tête Retry-After dans sa propre réponse d’erreur. Dans ce cas, le plus cohérent consiste à répercuter ce délai plutôt que d’en inventer un autre :
$delai = wp_remote_retrieve_header( $reponse_api, 'retry-after' );
$reponse->header( 'Retry-After', $delai ? $delai : '60' );Ce que le client de l’API peut faire de cette information
- Un client bien conçu peut lire l’en-tête
Retry-Afteret planifier automatiquement une nouvelle tentative après ce délai, plutôt que de réessayer immédiatement en boucle. - Un tableau de bord d’administration peut afficher un message clair à l’utilisateur, plutôt qu’une erreur technique brute.
- Des outils de supervision peuvent distinguer une vraie panne (code 500 persistant) d’une simple saturation temporaire (code 503 ponctuel).
Un piège à éviter : cacher un 503 comme un 200
Il est tentant, pour simplifier le développement côté client, de toujours renvoyer un code 200 avec un champ statut: erreur dans le corps de la réponse. Cette pratique casse la sémantique HTTP et empêche tout outil générique (proxy, moniteur de disponibilité, client HTTP standard) de réagir correctement à une indisponibilité réelle. Le code HTTP doit rester le reflet fidèle de la situation, indépendamment du contenu du corps de la réponse.
Un code d’erreur qui informe vaut toujours mieux qu’un code d’erreur qui se contente de constater — le client mérite de savoir combien de temps attendre, pas seulement que quelque chose a échoué.
En résumé
Face à une API tierce temporairement saturée, répondre 503 avec un en-tête Retry-After transforme une erreur opaque en information exploitable. Ce petit ajout, quelques lignes de code dans une route REST personnalisée, améliore sensiblement la robustesse perçue d’une intégration qui dépend d’un service externe hors de son contrôle direct.
