# Répondre 503 avec Retry-After quand une API tierce protégée est saturée

> Renvoyer un code d'attente explicite avec un délai indicatif informe correctement un client plutôt que de le laisser réessayer à l'aveugle.

- Auteur : WordPress Développement
- Publié le : 2022-02-21
- Mis à jour le : 2022-02-21
- Catégorie : Extensions
- URL : https://www.wpmoderne.fr/extensions/retry-after-503-api-tierce-saturee/

## L’essentiel

- Le code 503 signale une indisponibilité temporaire, pas une erreur définitive
- L'en-tête Retry-After donne une indication concrète au client
- WP_REST_Response transmet facilement ce code et cet en-tête

« 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 ?

> L'essentiel à retenir : Le code 503 signale une indisponibilité temporaire, pas une erreur définitive ; L'en-tête Retry-After donne une indication concrète au client ; WP_REST_Response transmet facilement ce code et cet en-tête

## 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-After` et 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.