Web et développement

Comment gérer les délais d'attente, les limites de taux et les tentatives dans PHP

How to Handle API Timeouts, Rate Limits, and Retries in PHP

Apprenez à créer des intégrations API PHP fiables avec des délais d'attente de connexion, la gestion des erreurs HTTP, un backoff exponentiel, le support Retry-After et des stratégies de reprise sûres.

Comment gérer les délais d’expiration API, les limites de débit et les nouvelles tentatives en PHP

Une intégration d’API fonctionne parfaitement pendant le développement. Puis, un jour, votre tâche planifiée s’arrête en cours de route. Un service distant répond avec HTTP 429, une connexion expire, ou une erreur HTTP 503 interrompt une synchronisation.

La tentation est de relancer immédiatement la requête.

Mais réessayer sans stratégie peut aggraver le problème. Cela peut surcharger une API déjà en difficulté, dépasser les limites de débit ou créer accidentellement des commandes et des paiements en double.

Un client API fiable a besoin de plus qu’un simple appel curl_exec() réussi.

Dans ce tutoriel, nous allons construire un client HTTP PHP pratique qui gère les délais d’expiration de connexion, les erreurs HTTP, les limites de débit et les défaillances temporaires. Nous expliquerons aussi quand il est sûr de réessayer, quand ce ne l’est pas, et comment diagnostiquer les problèmes en production.

Les exemples utilisent l’extension cURL intégrée à PHP, sans Composer ni dépendances tierces.

1. Comprendre les différents types de défaillances d’API

Toutes les requêtes infructueuses ne doivent pas être traitées de la même manière.

Échec Cause typique Action recommandée
Délai d’expiration de connexion Serveur inaccessible ou connexion lente Réessayer avec prudence
HTTP 400 Paramètres de requête invalides Corriger la requête
HTTP 401 Identifiants invalides ou expirés Vérifier l’authentification
HTTP 404 Ressource introuvable Vérifier l’identifiant de la ressource
HTTP 429 Limite de débit de l’API dépassée Respecter Retry-After
HTTP 500 Erreur interne du serveur Réessayer de manière sélective
HTTP 503 Indisponibilité temporaire du service Réessayer avec un délai
JSON invalide Format de réponse inattendu Journaliser et enquêter

Une erreur réseau est également différente d’une erreur HTTP.

Lorsqu’une API renvoie HTTP 500, la requête HTTP s’est terminée et le serveur a renvoyé une réponse d’erreur.

Lorsque cURL signale un échec de connexion, votre application pourrait ne pas avoir reçu de réponse HTTP du tout.

Cette distinction est importante pour décider s’il faut réessayer ou non.

2. Toujours configurer les délais d’expiration de connexion et de requête

PHP cURL fournit deux paramètres particulièrement utiles :

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

CURLOPT_CONNECTTIMEOUT limite la phase de connexion, tandis que CURLOPT_TIMEOUT limite la durée globale du transfert. Les deux sont documentés dans la référence officielle cURL de PHP.

Sans limites appropriées, un service externe lent peut occuper les workers PHP bien plus longtemps que prévu.

Un point de départ pratique pour une API JSON conventionnelle pourrait être cinq secondes pour l’établissement de la connexion et quinze secondes pour la requête complète.

Ce ne sont pas des valeurs universelles. Un téléversement de fichier ou la génération d’un rapport long peut nécessiter une politique de délai d’expiration différente.

Faites votre première requête API

<?php
declare(strict_types=1);

$url = 'https://api.example.com/products';

$curl = curl_init($url);

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => false,
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo(
    $curl,
    CURLINFO_HTTP_CODE
);

if ($response === false) {
    $error = curl_error($curl);

    curl_close($curl);

    throw new RuntimeException(
        'API request failed: ' . $error
    );
}

curl_close($curl);

echo 'HTTP status: ' . $statusCode;

Cela établit une base utile, mais ne gère pas encore les limites de débit ni les défaillances réessayables.

3. Comprendre HTTP 429 et Retry-After

HTTP 429 signifie que le client a envoyé trop de requêtes pendant une période définie par le fournisseur de l’API.

Certaines API imposent des limites par minute, par heure, par clé API ou par compte.

Un serveur peut répondre avec :

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

L’en-tête Retry-After indique au client combien de temps il doit attendre avant de réessayer.

L’en-tête peut contenir soit un nombre de secondes, soit une date HTTP.

Par exemple :

Retry-After: 120

Ou :

Retry-After: Wed, 25 Nov 2026 10:00:00 GMT

Un client bien élevé doit respecter cette instruction plutôt que d’envoyer des requêtes de façon répétée.

Si le serveur ne fournit pas de délai de nouvelle tentative, votre application a besoin d’une stratégie de repli.

4. Utiliser un backoff exponentiel plutôt que des nouvelles tentatives immédiates

Le backoff exponentiel augmente le temps d’attente après des échecs successifs.

Par exemple :

Nouvelle tentative Exemple de délai
1 1 seconde
2 2 secondes
3 4 secondes
4 8 secondes

Au lieu de réessayer chaque seconde, l’application attend de plus en plus longtemps.

Ajouter une petite variation aléatoire, appelée jitter, aide à empêcher de nombreux clients de réessayer simultanément.

Voici une fonction de délai réutilisable :

<?php
declare(strict_types=1);

function getRetryDelayMs(int $attempt): int
{
    $baseDelay = 1000;
    $maximumDelay = 30000;

    $exponentialDelay = min(
        $maximumDelay,
        $baseDelay * (2 ** ($attempt - 1))
    );

    return random_int(
        0,
        (int)$exponentialDelay
    );
}

Cela utilise un full jitter : le délai réel est sélectionné aléatoirement entre zéro et le plafond exponentiel.

Le délai aléatoire réduit les rafales de nouvelles tentatives synchronisées, bien qu’il ne remplace pas une instruction Retry-After explicite fournie par le serveur.

Illustration of the article's main concept

5. Construire un client API PHP réutilisable

Combinons les concepts précédents en une implémentation fonctionnelle.

Notre client :

  • Définir des délais d’expiration de connexion et de requête globale.
  • Renvoyer le statut HTTP et le corps de la réponse.
  • Détecter les défaillances de transport.
  • Réessayer certaines défaillances temporaires.
  • Respecter Retry-After lorsqu’il est présent.
  • Limiter le nombre de tentatives.
  • Éviter de relancer automatiquement les opérations non idempotentes.
<?php
declare(strict_types=1);

/**
 * Perform an HTTP GET request with bounded retries.
 *
 * Use only with trusted, configured API URLs.
 */
function apiGet(
    string $url,
    int $maxAttempts = 3
): array {
    if ($maxAttempts < 1) {
        throw new InvalidArgumentException(
            'maxAttempts must be at least 1.'
        );
    }

    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        $headers = [];

        $curl = curl_init($url);

        if ($curl === false) {
            throw new RuntimeException(
                'Unable to initialize cURL.'
            );
        }

        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPGET => true,
            CURLOPT_HEADERFUNCTION => static function (
                $curl,
                string $headerLine
            ) use (&$headers): int {
                $length = strlen($headerLine);

                if (str_starts_with(
                    $headerLine,
                    'HTTP/'
                )) {
                    $headers = [];
                }

                $position = strpos(
                    $headerLine,
                    ':'
                );

                if ($position !== false) {
                    $name = strtolower(trim(
                        substr($headerLine, 0, $position)
                    ));

                    $value = trim(
                        substr($headerLine, $position + 1)
                    );

                    $headers[$name] = $value;
                }

                return $length;
            },
        ]);

        $body = curl_exec($curl);
        $curlError = curl_errno($curl);
        $statusCode = (int)curl_getinfo(
            $curl,
            CURLINFO_HTTP_CODE
        );

        curl_close($curl);

        $transportFailure = $body === false;

        $retryableStatus = in_array(
            $statusCode,
            [408, 429, 500, 502, 503, 504],
            true
        );

        if (!$transportFailure && !$retryableStatus) {
            return [
                'status' => $statusCode,
                'body' => $body,
                'headers' => $headers,
                'attempts' => $attempt,
            ];
        }

        if ($attempt === $maxAttempts) {
            throw new RuntimeException(
                'API request failed after '
                . $attempt
                . ' attempts. HTTP '
                . $statusCode
                . ', cURL error '
                . $curlError
            );
        }

        $delayMs = min(
            30000,
            1000 * (2 ** ($attempt - 1))
        );

        $retryAfter = $headers['retry-after'] ?? null;

        if ($retryAfter !== null) {
            if (ctype_digit($retryAfter)) {
                $delayMs = (int)$retryAfter * 1000;
            } else {
                $timestamp = strtotime($retryAfter);

                if ($timestamp !== false) {
                    $delayMs = max(
                        0,
                        $timestamp - time()
                    ) * 1000;
                }
            }
        } else {
            $delayMs = random_int(
                0,
                (int)$delayMs
            );
        }

        // Do not block this worker indefinitely.
        if ($delayMs > 30000) {
            throw new RuntimeException(
                'Retry deferred: waiting time exceeds '
                . 'the synchronous retry budget.'
            );
        }

        usleep((int)$delayMs * 1000);
    }

    throw new RuntimeException(
        'Unexpected retry state.'
    );
}

Comment l’utiliser

<?php
declare(strict_types=1);

try {
    $result = apiGet(
        'https://api.example.com/products'
    );

    if ($result['status'] !== 200) {
        throw new RuntimeException(
            'Unexpected HTTP status: '
            . $result['status']
        );
    }

    $products = json_decode(
        $result['body'],
        true,
        512,
        JSON_THROW_ON_ERROR
    );

    echo 'API request completed after '
        . $result['attempts']
        . ' attempt(s).';

} catch (Throwable $exception) {
    error_log($exception->getMessage());
}

Cette implémentation est intentionnellement limitée aux requêtes GET vers des points de terminaison d’API de confiance.

Elle ne relance pas automatiquement les opérations POST, PUT, PATCH ou DELETE, car celles-ci nécessitent des protections supplémentaires.

Elle renvoie également à l’appelant les réponses HTTP non réessayables, celui-ci devant décider comment les traiter.

Pour les systèmes de production, vous devriez en outre valider les types de réponses, imposer des limites de taille de réponse et distinguer les erreurs de transport réessayables des échecs permanents TLS ou de configuration.

6. Pourquoi relancer des requêtes POST peut être dangereux

Imaginez une application e-commerce envoyant cette requête :

POST /api/orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 1
}

L’API distante crée la commande, mais la connexion tombe avant que votre application reçoive la réponse.

Votre application voit un délai d’expiration.

La commande a-t-elle échoué ?

Pas nécessairement. La commande peut déjà exister.

Si votre application relance immédiatement, elle pourrait créer une deuxième commande.

C’est pourquoi un délai d’expiration ne prouve pas qu’une opération a échoué sur le serveur.

Utiliser des clés d’idempotence lorsqu’elles sont prises en charge

Certaines API prennent en charge les clés d’idempotence.

Par exemple :

Idempotency-Key: order-8f7a2c

Lorsque l’API fournit un mécanisme d’idempotence documenté, réutiliser la même clé pour les nouvelles tentatives d’une même opération logique peut empêcher un traitement en double.

Mais ce comportement dépend de l’API. Ajouter un en-tête Idempotency-Key ne rend pas automatiquement une API arbitraire idempotente.

Pour les opérations impliquant des paiements, des commandes, des abonnements ou des modifications de base de données, suivez la documentation officielle du fournisseur concernant les nouvelles tentatives et l’idempotence.

Lorsqu’aucun mécanisme d’idempotence n’existe, vous devrez peut-être interroger le statut de l’opération ou réconcilier les résultats avant de tenter à nouveau.

7. Éviter d’utiliser sleep dans les requêtes web longues

Technical workflow illustration

Notre exemple utilise usleep() pour faciliter la compréhension du comportement des nouvelles tentatives.

Cela peut être acceptable pour de courtes opérations avec un budget de nouvelles tentatives étroitement contrôlé.

Cependant, un site de production ne devrait pas garder des workers PHP occupés pendant des minutes en attendant une API externe.

Supposons qu’une API réponde avec :

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Attendre une heure à l’intérieur d’une requête HTTP serait une mauvaise conception.

Une meilleure solution consiste à différer l’opération.

Par exemple, stockez un travail en attente :

Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC

Un worker planifié peut ensuite traiter le travail lorsqu’il devient éligible.

Cette approche est particulièrement utile pour :

  • La synchronisation de catalogue de produits.
  • L’envoi d’e-mails.
  • La publication sur les réseaux sociaux.
  • Le traitement de documents.
  • Les mises à jour d’inventaire.
  • Les imports d’API volumineux.

Elle rend aussi les défaillances plus faciles à surveiller et à récupérer.

8. Stocker les informations de nouvelle tentative dans une base de données

Pour une application adossée à MariaDB, une simple table de travaux pourrait ressembler à ceci :

CREATE TABLE api_jobs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    job_type VARCHAR(100) NOT NULL,
    payload_json LONGTEXT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    next_attempt_at DATETIME NOT NULL,
    last_error TEXT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    INDEX idx_jobs_ready (
        status,
        next_attempt_at
    )
);

Le worker sélectionne les travaux où :

SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;

Ce n’est que la partie sélection d’une implémentation de file d’attente.

Si plusieurs workers peuvent s’exécuter simultanément, les travaux doivent être réclamés de manière atomique, à l’aide d’une transaction et d’une stratégie de verrouillage appropriées, afin d’éviter un traitement en double.

Le worker devrait aussi appliquer un nombre maximal de nouvelles tentatives et déplacer les travaux qui échouent définitivement vers un état nécessitant une enquête.

Pour une petite application, cette approche adossée à une base de données peut suffire sans introduire Redis ni courtier de messages dédié.

9. Journaliser les défaillances sans exposer de données sensibles

Un journal d’API utile doit répondre à quatre questions :

  1. Quelle opération a échoué ?
  2. Quel service distant était impliqué ?
  3. Quel était le statut HTTP ou l’erreur de transport ?
  4. Quand l’application réessaiera-t-elle ?

Par exemple :

[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z

Évitez de journaliser les clés API, les jetons bearer, les en-têtes d’autorisation complets, les mots de passe ou des informations personnelles inutiles.

Si vous devez corréler des requêtes, utilisez un identifiant de requête généré.

Par exemple :

$requestId = bin2hex(random_bytes(8));

Vous pouvez inclure cet identifiant dans les journaux de l’application et, lorsque cela est pris en charge, l’envoyer à l’API distante.

10. Testez votre stratégie de nouvelle tentative avant la production

Un mécanisme de nouvelle tentative doit être testé face à des scénarios de défaillance prévisibles.

Vous n’avez pas besoin d’attendre une véritable panne d’API.

Un point de terminaison de test local peut renvoyer volontairement des codes de statut spécifiques.

Par exemple :

<?php
declare(strict_types=1);

header('Content-Type: application/json');

http_response_code(429);
header('Retry-After: 3');

echo json_encode([
    'error' => 'rate_limit_exceeded',
]);

Exécutez ce point de terminaison uniquement dans un environnement de test local ou protégé.

Vérifiez ensuite que votre client :

  • Détecte HTTP 429.
  • Lit l’en-tête Retry-After.
  • Attend avant de réessayer.
  • S’arrête après le nombre configuré de tentatives.
  • Enregistre la défaillance sans exposer de secrets.

Répétez avec HTTP 503 et un point de terminaison volontairement lent.

Testez aussi une réponse HTTP 400 pour confirmer que le client ne réessaie pas les erreurs de requête permanentes.

Enfin, testez une opération qui a pu réussir avant l’échec de la connexion. Cela est essentiel pour les intégrations de paiement et de commande.

11. Une liste de contrôle de production pour des intégrations API fiables

Avant de déployer une intégration API, vérifiez les éléments suivants :

Contrôle Comportement attendu
Délai d’expiration de connexion Défini et testé
Délai d’expiration global Défini et testé
HTTP 429 Respecte les limites de débit
HTTP 5xx Réessaie de manière sélective
HTTP 4xx Aucune nouvelle tentative aveugle
Limite de nouvelles tentatives Empêche les boucles infinies
Délai de nouvelle tentative Backoff avec jitter
Opérations POST Idempotence ou réconciliation
Périodes d’attente longues Différées vers un worker
Journaux Utiles, privés, assainis
Concurrence des workers Exécution en double empêchée
Défaillances permanentes Visibles et récupérables

Conclusion : des API fiables exigent une gestion contrôlée des défaillances

Les API externes ne sont jamais parfaitement disponibles.

Même un service bien entretenu peut subir une surcharge temporaire, des interruptions réseau ou une limitation de débit.

L’objectif n’est pas d’éliminer chaque défaillance. Il est de faire en sorte que votre application réponde de manière prévisible lorsque des défaillances surviennent.

Commencez avec des délais d’expiration raisonnables et une gestion explicite des erreurs HTTP. Ajoutez des nouvelles tentatives limitées avec un backoff exponentiel, respectez les délais de nouvelle tentative fournis par le serveur et évitez de répéter automatiquement des opérations susceptibles de créer des données en double.

Pour des intégrations plus complexes, déplacez les nouvelles tentatives vers une file de travaux persistante plutôt que de maintenir des requêtes web ouvertes.

Ces principes s’appliquent à presque toutes les applications PHP modernes, qu’il s’agisse de développer une extension CMS, de synchroniser un catalogue e-commerce, d’envoyer des e-mails transactionnels ou d’intégrer un service de paiement.

Un client API fiable est celui qui sait non seulement comment envoyer une requête, mais aussi quand réessayer, quand attendre et quand s’arrêter.

Références officielles